wendkeep 0.52.0 → 0.54.0

package/CHANGELOG.md

@@ -4,6 +4,65 @@ 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.54.0] — 2026-07-25
+
+### Added
+
+- **`wendkeep sync [--project P]`** — roda `init` → `sync-defs` → `doctor` no **projeto
+  corrente**, num comando só. São os três passos que se repetem idênticos depois de cada
+  atualização do pacote; repetir à mão convida a esquecer o `sync-defs`, e aí as skills
+  `wk-*` ficam na versão anterior enquanto o pacote já é o novo. Para no primeiro passo que
+  falha. O `npm install` fica **fora** de propósito: um processo não se auto-substitui e
+  continua rodando, e é o passo que mais varia entre projetos (npm/pnpm/workspace/cooldown).
+  O comando opera onde é invocado, nunca sobre uma lista de repositórios — o wendkeep é um
+  pacote público. Capability `cli-safety` (CLI-SYNC-1).
+
+### Fixed
+
+- **`sync` blinda contra o *env bleed*.** O vault é re-resolvido com `resolveProjectVault`
+  **depois** do `init` (que pode tê-lo acabado de criar) e repassado explícito aos passos
+  seguintes. Sem isso, `sync-defs` cairia em `OBSIDIAN_VAULT_PATH` e, num projeto novo, o
+  env global da máquina levaria as skills para o vault de outro projeto. Capability
+  `project-vault-routing` (PVR-SYNC-1).
+
+### Changed
+
+- **`runSyncDefs` e `runDoctor` devolvem o código de saída** em vez de chamar
+  `process.exit`; quem sai é o `bin`. Ambos saíam incondicionalmente, o que matava o
+  processo no segundo passo de qualquer encadeamento. Os códigos de saída observáveis de
+  `wendkeep doctor` e `wendkeep sync-defs` não mudaram. Capability `cli-safety` (CLI-SYNC-2).
+
+## [0.53.0] — 2026-07-25
+
+### Fixed
+
+- **As seções derivadas do corpo refletem a sessão inteira.** O `## Encerramento` listava 15
+  decisões e 5 aprendizados enquanto o corpo da nota mostrava 3 decisões e *"Nenhum
+  aprendizado registrado ainda."* — medido num vault real. A causa é ausência de escrita:
+  os placeholders nascem no template e, depois disso, só `decision-capture` escrevia — e
+  apenas ADRs capturados via `AskUserQuestion`. As seções de **Bugs e Aprendizados nunca
+  tiveram writer nenhum**. O dado certo já estava no lugar certo e era descartado:
+  `finalizeSessionFile` recebe a lista mesclada (capturados + varredura) e usava só para o
+  Encerramento; agora as três seções saem do mesmo objeto, na mesma passada.
+- **A proveniência declarada manda na atribuição.** `noteReferencesSession` casava substring
+  no arquivo inteiro, então uma derivada que citava outra sessão em `related:` era atribuída
+  às duas — caso real: um BUG com `session:` de uma sessão e `source:` de outra ia para
+  ambas. Agora `source:` decide quando existe; sem ele (nota legada) qualquer referência
+  ainda vale, preservando DRV-5. Capability `derived-notes` (DRV-10, DRV-12).
+
+### Added
+
+- **`wendkeep note repair-sections [--apply] [--json]`** — reconstrói as seções derivadas
+  das notas já fechadas, que não se corrigem sozinhas (o fecho só roda em sessão que ainda
+  fecha). Lê as derivadas uma vez e indexa por sessão (O(N+M), não O(N·M)); dry-run por
+  padrão; grava sob o mesmo lock dos hooks. Descarta o placeholder em qualquer variante,
+  **preserva prosa** escrita na seção, e é no-op em nota que não tem os headings.
+  Capability `derived-notes` (DRV-11).
+- **`wendkeep doctor` surfaça seções derivadas desatualizadas.** Nova seção `[derivadas]`
+  com as notas afetadas, quantos links faltam e o comando de reparo. Só falta conta como
+  sintoma — link a mais pode ser curadoria do dono do vault. Capability `vault-doctor`
+  (DIAG-6).
+
 ## [0.52.0] — 2026-07-25
 
 ### Fixed

package/bin/wendkeep.mjs

@@ -42,6 +42,12 @@ Usage:
   wendkeep hook <name>         Run a session hook (used by settings.json). Reads the
                            agent's JSON on stdin. Names: ${RUNNABLE_HOOKS.join(', ')}.
 
+  wendkeep sync [--project P]  Run init -> sync-defs -> doctor on the CURRENT project, in one
+                           command — the three steps that repeat identically after every
+                           package update. Stops at the first failing step. Install the
+                           package first (npm i -D wendkeep@latest); a running process
+                           cannot replace itself. · --vault P · --yes.
+
   wendkeep doctor [--vault P]  Run a vault health check.
   wendkeep change <sub>        Change lifecycle: new [--simple] | use | bind <slug> --session <id> | continue | list | show |
                            status | done <id> | undone <id> | diff | archive [--force] | abandon | relink | backlink.
@@ -84,6 +90,9 @@ Usage:
                            (damage from pre-lock concurrent writes) into a single block: base keys
                            from the original block, values from the newest. Dry-run by default;
                            --apply writes under the same lock as the hooks · --json.
+  wendkeep note repair-sections [--apply]  Rebuild the derived sections (decisions/bugs/learnings)
+                           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 validate-memory [path]  Validate .brain/CORE.md against the compaction
                            protocol (cap 25, 3 sections, no secrets/PII). Uses
@@ -162,7 +171,12 @@ async function main() {
       break;
     case 'doctor': {
       const { runDoctor } = await import('../src/doctor.mjs');
-      runDoctor(rest);
+      process.exit(runDoctor(rest));
+      break;
+    }
+    case 'sync': {
+      const { runSync } = await import('../src/sync.mjs');
+      process.exit(await runSync(rest));
       break;
     }
     case 'validate-memory': {
@@ -172,7 +186,7 @@ async function main() {
     }
     case 'sync-defs': {
       const { runSyncDefs } = await import('../src/sync-defs.mjs');
-      runSyncDefs(rest);
+      process.exit(runSyncDefs(rest));
       break;
     }
     case 'change': {

package/hooks/derived-sections.mjs

@@ -0,0 +1,208 @@
+// As três seções derivadas do corpo da nota de sessão: Decisões, Bugs e Aprendizados.
+//
+// Até a 0.52.0 ninguém escrevia nas seções de bug e aprendizado, e a de decisões só recebia
+// os ADRs capturados via AskUserQuestion — um ADR gerado por `change archive` aparecia no
+// Encerramento e nunca no corpo. Num vault real: 15 decisões e 5 aprendizados no
+// Encerramento contra 3 decisões e um placeholder no corpo.
+//
+// O fecho (finalizeSessionFile) e o reparo retroativo (repairDerivedSections) usam as MESMAS
+// funções daqui. Foi a lição do note repair-frontmatter: quando reparo e comportamento
+// corrente divergem, o doctor passa a acusar o que o reparo não conserta.
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { getLocale } from './locale.mjs';
+import { mutateSessionNote } from './session-note-io.mjs';
+import { toVaultRelative, wikilinkFromRel } from './obsidian-common.mjs';
+
+export const DERIVED_SECTIONS = [
+  { key: 'decisions', heading: 'Decisões geradas nesta sessão', folderKey: 'decisions' },
+  { key: 'bugs', heading: 'Bugs gerados nesta sessão', folderKey: 'bugs' },
+  { key: 'learnings', heading: 'Aprendizados gerados nesta sessão', folderKey: 'learnings' },
+];
+
+// Ordena pelo caminho: agrupa por tipo e deixa a numeração (ADR-0003, ADR-0005, …) em ordem.
+// O Encerramento herda a ordem de varredura do filesystem, que não é garantida.
+export function derivedSectionLines(items) {
+  return [...new Set(items || [])].sort().map((rel) => `- ${wikilinkFromRel(rel)}`);
+}
+
+// Aplica as três seções ao conteúdo. Fecho e reparo passam por aqui — se cada um tivesse
+// seu upsert, voltariam a divergir (a lição do note repair-frontmatter).
+export function applyDerivedSections(content, created) {
+  let next = content;
+  for (const { key, heading } of DERIVED_SECTIONS) {
+    // Lista vazia devolve o conteúdo intocado, então a seção sem itens mantém o
+    // placeholder — seção vazia é informação ("não gerou aprendizado"), não defeito.
+    next = defaultUpsert(next, heading, derivedSectionLines(created?.[key]));
+  }
+  return next;
+}
+
+const SESSION_LINK = /\[\[((?:02-Sess|02-Session)[^\]|]+)/g;
+
+// A sessão que GEROU a nota, não toda sessão que a nota cita.
+//
+// `findLinkedDerivedNotes` casa por substring no arquivo inteiro, então uma derivada que
+// menciona outra sessão em `related:` ou na prosa é atribuída às duas. Caso real neste
+// vault: BUG-0001 declara `session:` de uma sessão e `source:`/`related:` de outra, e a
+// varredura devolve a nota para ambas. No Encerramento o erro é regenerado a cada reopen;
+// escrito no corpo ele fica. Por isso a proveniência declarada manda quando existe.
+export function provenanceSessions(content) {
+  const fm = content.match(/^---\n([\s\S]*?)\n---/);
+  const scope = fm ? fm[1] : content;
+  // `source:` é o campo de proveniência canônico do vault — é o que `note relink` faz
+  // backfill (DRV-9). Só quando ele falta (nota legada) caímos para qualquer referência.
+  const source = scope.match(/^source:\n((?:\s+- .*\n?)+)/m) || scope.match(/^source:\s*(.+)$/m);
+  const hay = source ? source[1] : content;
+  const found = new Set();
+  for (const m of hay.matchAll(SESSION_LINK)) found.add(m[1].trim());
+  return [...found];
+}
+
+// Lê as notas derivadas UMA vez e indexa por sessão referenciada. O fecho pode varrer por
+// sessão (uma só, custo irrelevante); o reparo percorre N sessões e pagaria O(N*M) leituras.
+export function indexDerivedBySession(vaultBase) {
+  const folders = getLocale(vaultBase).folders;
+  const index = new Map(); // sessão (rel, sem .md) -> { decisions:[], bugs:[], learnings:[] }
+
+  const record = (sessionKey, key, rel) => {
+    if (!index.has(sessionKey)) index.set(sessionKey, { decisions: [], bugs: [], learnings: [] });
+    index.get(sessionKey)[key].push(rel);
+  };
+
+  for (const { key, folderKey } of DERIVED_SECTIONS) {
+    const walk = (dir) => {
+      let entries = [];
+      try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+      for (const entry of entries) {
+        const abs = join(dir, entry.name);
+        if (entry.isDirectory()) { walk(abs); continue; }
+        if (!entry.name.endsWith('.md')) continue;
+        let content;
+        try { content = readFileSync(abs, 'utf-8'); } catch { continue; }
+        const rel = toVaultRelative(vaultBase, abs);
+        for (const target of provenanceSessions(content)) record(target, key, rel);
+      }
+    };
+    walk(join(vaultBase, folders[folderKey]));
+  }
+  return index;
+}
+
+const SESSIONS_DIR_CANDIDATES = ['02-Sessões', '02-Sessions'];
+
+export function listSessionNotes(vaultBase) {
+  const out = [];
+  for (const dirName of SESSIONS_DIR_CANDIDATES) {
+    const walk = (dir) => {
+      let entries = [];
+      try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+      for (const entry of entries) {
+        const abs = join(dir, entry.name);
+        if (entry.isDirectory()) { walk(abs); continue; }
+        if (entry.name.endsWith('.md')) out.push(abs);
+      }
+    };
+    walk(join(vaultBase, dirName));
+  }
+  return out;
+}
+
+const sectionBody = (content, heading) => {
+  const i = content.indexOf(`## ${heading}`);
+  if (i < 0) return null;
+  const j = content.indexOf('\n## ', i + 3);
+  return content.slice(i, j < 0 ? content.length : j);
+};
+
+// O que a nota DEVERIA listar mas não lista. Excedente (link posto à mão) não é sintoma
+// deste bug e não é reportado — pode ser curadoria do dono do vault.
+export function missingDerivedLinks(content, entry) {
+  const missing = { decisions: [], bugs: [], learnings: [] };
+  for (const { key, heading } of DERIVED_SECTIONS) {
+    const body = sectionBody(content, heading);
+    if (body === null) continue;
+    for (const rel of entry?.[key] || []) {
+      const link = wikilinkFromRel(rel);
+      if (!body.includes(link) && !body.includes(rel)) missing[key].push(rel);
+    }
+  }
+  return missing;
+}
+
+export const countMissing = (missing) =>
+  DERIVED_SECTIONS.reduce((n, { key }) => n + (missing[key]?.length || 0), 0);
+
+// Junta o que a seção já lista com o que o índice conhece, para que o reparo seja aditivo:
+// um link posto à mão sobrevive ao conserto.
+function mergedForNote(entry) {
+  return {
+    decisions: entry?.decisions || [],
+    bugs: entry?.bugs || [],
+    learnings: entry?.learnings || [],
+  };
+}
+
+export function repairDerivedSections(vaultBase, { apply = false, lockTimeoutMs } = {}) {
+  const index = indexDerivedBySession(vaultBase);
+  const repaired = [];
+  const skipped = [];
+
+  for (const abs of listSessionNotes(vaultBase)) {
+    const rel = relative(vaultBase, abs).replaceAll('\\', '/');
+    const entry = index.get(rel.replace(/\.md$/, '')) || index.get(rel);
+    if (!entry) continue;
+
+    let content;
+    try { content = readFileSync(abs, 'utf-8'); } catch { skipped.push({ file: rel, reason: 'leitura falhou' }); continue; }
+
+    const missing = countMissing(missingDerivedLinks(content, entry));
+    if (!missing) continue;
+
+    if (!apply) { repaired.push({ file: rel, missing }); continue; }
+
+    const outcome = mutateSessionNote(
+      abs,
+      (original) => applyDerivedSections(original, mergedForNote(entry)),
+      lockTimeoutMs ? { timeoutMs: lockTimeoutMs } : {},
+    );
+    if (!outcome.written) { skipped.push({ file: rel, reason: `gravação não ocorreu (${outcome.reason})` }); continue; }
+    repaired.push({ file: rel, missing });
+  }
+
+  return { applied: apply, repaired, skipped };
+}
+
+// O placeholder do template ("Nenhuma decisão registrada ainda.") não começa com `- `, então
+// o filtro de lista já o descarta. Mas a variante COM bullet passaria no filtro e viveria
+// para sempre junto dos links reais — é o mesmo caso que `shouldDropFileListLine` já cobre
+// defensivamente nas seções de arquivos.
+export const isDerivedPlaceholder = (line) => /^-?\s*Nenhum[ao]?\s+\S+.*registrad[ao]s?\s+ainda\.?$/i.test(line.trim());
+
+// Upsert próprio (o reparo não pode depender do hook de Stop, que carrega transcript, locale
+// e o mundo). Duas diferenças deliberadas em relação ao upsertListSection do session-stop:
+// descarta o placeholder em qualquer variante, e PRESERVA prosa — uma nota que o dono do
+// vault escreveu na seção não pode sumir num conserto automático.
+function defaultUpsert(content, heading, lines) {
+  if (!lines.length) return content;
+  const marker = `\n## ${heading}\n`;
+  const start = content.indexOf(marker);
+  if (start === -1) return content; // heading ausente: nunca inventa seção em nota alheia
+  const bodyStart = start + marker.length;
+  const nextRel = content.slice(bodyStart).search(/\n## /);
+  const bodyEnd = nextRel === -1 ? content.length : bodyStart + nextRel;
+
+  const prose = [];
+  const items = [];
+  const add = (line) => { if (!items.includes(line)) items.push(line); };
+  for (const raw of content.slice(bodyStart, bodyEnd).split('\n')) {
+    const line = raw.trimEnd();
+    if (!line.trim() || isDerivedPlaceholder(line)) continue;
+    if (line.startsWith('- ')) add(line);
+    else prose.push(line); // comentário do agente/dono do vault: sobrevive ao conserto
+  }
+  for (const line of lines) add(line);
+
+  const body = [...prose, ...(prose.length ? [''] : []), ...items].join('\n');
+  return `${content.slice(0, bodyStart)}\n${body}\n\n${content.slice(bodyEnd).replace(/^\n+/, '')}`;
+}

package/hooks/harness-doctor.mjs

@@ -7,6 +7,7 @@ import { relinkDerivedNotes } from './linked-notes.mjs';
 import { buildEffectiveRequirementPackage, checkSpecsState, evaluateVerdict, tasksHashOf, validateSpecImpact } from './spec-core.mjs';
 import { getLocale } from './locale.mjs';
 import { priceForModel } from './token-usage.mjs';
+import { countMissing, indexDerivedBySession, listSessionNotes, missingDerivedLinks } from './derived-sections.mjs';
 import { readControl } from './obsidian-common.mjs';
 
 export function checkHarness(vaultBase, projectRoot) {
@@ -179,6 +180,34 @@ export function renderUnpricedModelLines(unpriced) {
   return lines;
 }
 
+// As seções derivadas do corpo da nota de sessão ficavam para trás do Encerramento: num
+// vault real, 15 decisões e 5 aprendizados listados no fecho contra 3 e um placeholder no
+// corpo. Notas fechadas antes da correção não se consertam sozinhas — o doctor as aponta.
+export function checkStaleDerivedSections(vaultBase) {
+  const index = indexDerivedBySession(vaultBase);
+  const notes = [];
+
+  for (const abs of listSessionNotes(vaultBase)) {
+    const rel = relative(vaultBase, abs).replaceAll('\\', '/');
+    const entry = index.get(rel.replace(/\.md$/, '')) || index.get(rel);
+    if (!entry) continue;
+    let content;
+    try { content = readFileSync(abs, 'utf-8'); } catch { continue; }
+    // Só falta conta. Link a mais pode ser curadoria do dono do vault, não sintoma.
+    const missing = countMissing(missingDerivedLinks(content, entry));
+    if (missing) notes.push({ file: rel, missing });
+  }
+  return { notes };
+}
+
+export function renderStaleDerivedSectionLines(stale) {
+  const lines = [`[derivadas] ${stale.notes.length} sessão(ões) com seções desatualizadas`];
+  for (const { file, missing } of stale.notes) lines.push(`  ✗ ${file} (${missing} link(s) faltando)`);
+  if (stale.notes.length) lines.push('  → wendkeep note repair-sections --apply');
+  else lines.push('  seções derivadas em dia ✓');
+  return lines;
+}
+
 // Formatador puro pra que a saída do doctor seja testável sem process.exit.
 export function renderStackedFrontmatterLines(vaultBase, stacked) {
   const lines = [`[notas] ${stacked.count} sessão(ões) com frontmatter empilhado`];

package/hooks/session-stop.mjs

@@ -11,6 +11,7 @@ import { getLocale } from './locale.mjs';
 import { updateSessionObservability } from './session-observability.mjs';
 import { resolveSessionEntry } from './session-identity.mjs';
 import { mutateSessionNote } from './session-note-io.mjs';
+import { applyDerivedSections, provenanceSessions } from './derived-sections.mjs';
 import {
   ensureDir,
   findActiveSessionByTranscript,
@@ -804,6 +805,14 @@ export function extractPending(text) {
 }
 
 function noteReferencesSession(content, sessionRel) {
+  // Quando a derivada declara `source:`, ele manda: uma nota que apenas CITA outra sessão
+  // (em `related:` ou na prosa) não pertence a ela. Sem `source:` (nota legada), qualquer
+  // referência vale — é o que DRV-5 estabeleceu e o que `note relink` existe para corrigir.
+  const declared = provenanceSessions(content);
+  if (declared.length) {
+    const key = sessionRel.replace(/\.md$/, '').replaceAll('\\', '/');
+    return declared.some((target) => target.replace(/\.md$/, '') === key);
+  }
   const sessionLink = wikilinkFromRel(sessionRel);
   return content.includes(sessionRel) || content.includes(sessionLink);
 }
@@ -924,7 +933,12 @@ ${formatPendingClosing(pending)}
 `;
 
   mutateSessionNote(sessionPath, (content) => replaceClosingSection(
-    replacePendingSection(updateFrontmatter(content, endedAt), pending),
+    // As três seções derivadas saem do MESMO `created` que monta o Encerramento — antes
+    // elas ficavam de fora deste write e a nota mentia no corpo (ver hooks/derived-sections.mjs).
+    applyDerivedSections(
+      replacePendingSection(updateFrontmatter(content, endedAt), pending),
+      created,
+    ),
     closing,
   ));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.52.0",
+  "version": "0.54.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.49.0"
+    "wendkeep": "^0.52.0"
   }
 }

package/src/doctor.mjs

@@ -4,7 +4,7 @@ import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { checkHarness, checkVaultLinks, checkSessionActivity, checkStackedFrontmatter, renderStackedFrontmatterLines, checkUnpricedModels, renderUnpricedModelLines } from '../hooks/harness-doctor.mjs';
+import { checkHarness, checkVaultLinks, checkSessionActivity, checkStackedFrontmatter, renderStackedFrontmatterLines, checkUnpricedModels, renderUnpricedModelLines, checkStaleDerivedSections, renderStaleDerivedSectionLines } from '../hooks/harness-doctor.mjs';
 import { checkSyncDefs } from './sync-defs.mjs';
 import { resolveProjectVault } from './project-vault.mjs';
 
@@ -34,7 +34,7 @@ export function runDoctor(argv) {
     });
   } catch (error) {
     process.stderr.write(`wendkeep doctor: ${error.message}\n`);
-    process.exit(2);
+    return 2;
   }
   const vaultBase = resolution.base;
   process.stdout.write(`[vault] ${resolution.source}: ${vaultBase} (project: ${projectRoot})\n`);
@@ -76,6 +76,9 @@ export function runDoctor(argv) {
   // 3c. Modelo fora de pricing.json fecha a sessão com custo zero, sem erro — só aparece aqui.
   process.stdout.write(`\n${renderUnpricedModelLines(checkUnpricedModels(vaultBase)).join('\n')}\n`);
 
+  // 3d. Seções derivadas do corpo que ficaram para trás do Encerramento (notas pré-0.53.0).
+  process.stdout.write(`\n${renderStaleDerivedSectionLines(checkStaleDerivedSections(vaultBase)).join('\n')}\n`);
+
   // 4. Sessão: não mente "inativa" quando há atividade recente (workflow/subagente em background).
   const act = checkSessionActivity(vaultBase);
   if (act.lastSession) {
@@ -87,5 +90,7 @@ export function runDoctor(argv) {
     process.stdout.write(`[sessão] última: ${act.lastSession} (${label})\n`);
   }
 
-  process.exit(healthStatus !== 0 || errors.length ? 1 : 0);
+  // Devolve o código em vez de sair: `wendkeep sync` encadeia este comando, e um
+  // process.exit aqui mataria a cadeia. Quem faz o exit é o bin.
+  return healthStatus !== 0 || errors.length ? 1 : 0;
 }

package/src/note.mjs

@@ -16,6 +16,7 @@ import {
 import { getLocale } from '../hooks/locale.mjs';
 import { buildManualBugNote, buildManualLearningNote, relinkDerivedNotes } from '../hooks/linked-notes.mjs';
 import { repairStackedFrontmatter } from '../hooks/frontmatter-repair.mjs';
+import { repairDerivedSections } from '../hooks/derived-sections.mjs';
 
 const TYPES = {
   bug: { folderKey: 'bugs', prefix: 'BUG', build: buildManualBugNote },
@@ -60,8 +61,22 @@ export function runNote(argv) {
     process.exit(0);
   }
 
+  if (sub === 'repair-sections') {
+    const vaultRaw = opt(rest, '--vault') || process.env.OBSIDIAN_VAULT_PATH;
+    if (!vaultRaw) { process.stderr.write('wendkeep note repair-sections: 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 repair-sections: vault not found: ${vaultBase}\n`); process.exit(2); }
+    const r = repairDerivedSections(vaultBase, { apply: rest.includes('--apply') });
+    if (rest.includes('--json')) { process.stdout.write(`${JSON.stringify(r, null, 2)}\n`); process.exit(0); }
+    process.stdout.write(`${r.repaired.length} sessão(ões) com seções derivadas desatualizadas${r.applied ? ' reparada(s)' : ' seriam reparada(s)'}\n`);
+    for (const n of r.repaired) process.stdout.write(`  ${n.file} (${n.missing} link(s) faltando)\n`);
+    for (const s of r.skipped) process.stdout.write(`  pulado: ${s.file} (${s.reason})\n`);
+    if (!r.applied && r.repaired.length) process.stdout.write('\ndry-run — nada escrito. Rode com --apply para reconstruir as seções.\n');
+    process.exit(0);
+  }
+
   if (sub !== 'new') {
-    process.stderr.write('wendkeep note: subcomando desconhecido (use `note new --type bug|learning "<título>"`, `note relink [--apply]` ou `note repair-frontmatter [--apply]`).\n');
+    process.stderr.write('wendkeep note: subcomando desconhecido (use `note new --type bug|learning "<título>"`, `note relink [--apply]`, `note repair-frontmatter [--apply]` ou `note repair-sections [--apply]`).\n');
     process.exit(2);
   }
 

package/src/sync-defs.mjs

@@ -173,7 +173,7 @@ export function runSyncDefs(argv) {
   const base = vault || process.env.OBSIDIAN_VAULT_PATH;
   if (!base) {
     process.stderr.write('wendkeep sync-defs: no vault. Pass --vault <path> or set OBSIDIAN_VAULT_PATH.\n');
-    process.exit(2);
+    return 2;
   }
   const vaultBase = isAbsolute(base) ? base : resolve(process.cwd(), base);
   const projectPath = resolve(project || process.cwd());
@@ -184,7 +184,7 @@ export function runSyncDefs(argv) {
       process.stderr.write(`wendkeep sync-defs --check: drift detectado\n  - ${r.issues.join('\n  - ')}\n`);
       process.stderr.write('rode `wendkeep sync-defs --reseed` e reinicie Claude Code/Codex\n');
     }
-    process.exit(r.ok ? 0 : 1);
+    return r.ok ? 0 : 1;
   }
   // --reseed (0.31.0): sobrescreve as wk-* de .brain/skills com os seeds da versão instalada
   // ANTES de copiar — é como um vault existente recebe descriptions/HARD-GATE novos.
@@ -198,7 +198,8 @@ export function runSyncDefs(argv) {
   );
   if (r.agents.length) process.stdout.write(`  agents: ${r.agents.join(', ')}\n`);
   if (r.skills.length) process.stdout.write(`  skills: ${r.skills.join(', ')}\n`);
-  process.exit(0);
+  // Devolve o código:  encadeia este comando (ver src/sync.mjs).
+  return 0;
 }
 
 // --- seeding (init) ---------------------------------------------------------

package/src/sync.mjs

@@ -0,0 +1,76 @@
+// `wendkeep sync` — os três passos que se repetem iguais a cada atualização do pacote:
+// init -> sync-defs -> doctor, no PROJETO CORRENTE.
+//
+// O `npm install` fica de fora de propósito: um processo não se auto-substitui e continua
+// rodando (o código em execução seguiria sendo o antigo), e é o passo que mais varia entre
+// projetos — npm, pnpm, workspace root, política de cooldown. É onde um comando "esperto"
+// quebraria no repositório de outra pessoa.
+//
+// E opera onde é invocado, nunca sobre uma lista de projetos: o wendkeep é um pacote
+// público, e um comando que varresse repositórios por nome só funcionaria numa máquina.
+import { resolve } from 'node:path';
+
+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;
+}
+
+const step = (n, label) => process.stdout.write(`\n[${n}/3] ${label}\n`);
+
+export async function runSync(argv) {
+  const projectRaw = opt(argv, '--project');
+  const vaultRaw = opt(argv, '--vault');
+  const projectPath = resolve(projectRaw && !projectRaw.startsWith('--') ? projectRaw : process.cwd());
+  const passthrough = argv.filter((a) => a === '--yes' || a === '-y' || a === '--force');
+
+  // 1. init — idempotente: refaz a fiação sem sobrescrever o que já está configurado.
+  step(1, 'init');
+  const { runInit } = await import('./init.mjs');
+  try {
+    await runInit(['--project', projectPath, ...(vaultRaw ? ['--vault', vaultRaw] : []), ...passthrough]);
+  } catch (error) {
+    process.stderr.write(`wendkeep sync: init falhou — ${error.message}\n`);
+    return 1;
+  }
+
+  // Resolve o vault DEPOIS do init (que pode tê-lo acabado de criar) e repassa explícito.
+  // Sem isso, sync-defs cairia em `--vault || OBSIDIAN_VAULT_PATH` e o env global da
+  // máquina sequestraria um projeto recém-inicializado — o env bleed conhecido.
+  let vaultBase;
+  try {
+    const { resolveProjectVault } = await import('./project-vault.mjs');
+    vaultBase = resolveProjectVault({
+      startDir: projectPath,
+      explicitVault: vaultRaw || '',
+      validateIdentity: !vaultRaw,
+    }).base;
+  } catch (error) {
+    process.stderr.write(`wendkeep sync: vault não resolvido — ${error.message}\n`);
+    return 2;
+  }
+
+  // 2. sync-defs — propaga as skills/agents da versão instalada para o projeto.
+  step(2, 'sync-defs');
+  const { runSyncDefs } = await import('./sync-defs.mjs');
+  const defsCode = runSyncDefs(['--vault', vaultBase, '--project', projectPath]);
+  if (defsCode) {
+    // Seguir para o doctor aqui seria enganoso: ele acusaria um `defs stale` que este
+    // passo deveria ter resolvido.
+    process.stderr.write('wendkeep sync: sync-defs falhou — doctor não executado.\n');
+    return defsCode;
+  }
+
+  // 3. doctor — relata. Sair != 0 é o resultado esperado num vault com pendências, então o
+  // código é propagado sem ser tratado como falha da cadeia.
+  step(3, 'doctor');
+  const { runDoctor } = await import('./doctor.mjs');
+  const doctorCode = runDoctor(['--vault', vaultBase, '--project', projectPath]);
+
+  // Nunca afirmar "tudo em dia": o doctor sai 0 mesmo tendo listado órfãos, seções
+  // desatualizadas ou modelos sem preço — essas checagens não são fatais. Uma linha final
+  // otimista contradiria o relatório logo acima dela.
+  process.stdout.write(`\nwendkeep sync: 3 passo(s) concluído(s)${doctorCode ? ' — doctor reportou erros' : ' — veja o relatório do doctor acima'}\n`);
+  return doctorCode;
+}