wendkeep 0.31.0 → 0.32.0

package/CHANGELOG.md

@@ -4,6 +4,50 @@ 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.32.0] — 2026-07-09
+
+### Added
+
+- **Contrato explícito `spec_impact`** para changes novas: `pending`, `required` ou `none`.
+  Changes materiais (`required`) precisam listar a capability e manter um delta real em
+  `specs/<capability>/spec.md`; `none` exige justificativa em `spec_impact_reason`.
+- **Snapshots imutáveis de planos aprovados** em `planos/<sha256-12>.md`, deduplicados por
+  conteúdo. `plano-aprovado.md` passa a ser o índice dos snapshots, sem sobrescrever planos
+  anteriores da mesma change.
+- Diagnósticos de `spec_impact` no `wendkeep doctor`, incluindo estado pendente, delta ausente e
+  divergência entre `specs:` e o conteúdo real no disco.
+
+### Changed
+
+- Hooks Claude de alta frequência usam `node` com caminho ancorado em
+  `${CLAUDE_PROJECT_DIR}`. O `init` migra automaticamente os comandos relativos de 0.31.0 sem
+  duplicar grupos, inclusive quando o agente muda o `cwd` para um subprojeto.
+- `wk-workflow`, `wk-brainstorming`, `wk-planning` e o roteador de SessionStart agora exigem a
+  classificação do impacto, o delta da capability e a rastreabilidade `[req:ID]` antes do archive.
+- O archive passa a ser **fail-closed** para specs: placeholder, arquivo ausente ou falha de
+  promoção bloqueiam o move e a criação do ADR.
+- Ao arquivar, links da sessão para a change ativa são reescritos para o caminho em `_arquivo`.
+  Decisões capturadas também entram imediatamente na seção de decisões da sessão ativa.
+
+### Fixed
+
+- **Planos aprovados descartados no Claude Code atual**: `plan-capture` agora lê
+  `tool_response.plan` no payload estruturado de `PostToolUse:ExitPlanMode`, mantendo os formatos
+  textuais legados e rejeições como no-op.
+- **52 falhas `MODULE_NOT_FOUND` observadas em produção** quando `change-warn`/`change-guard`
+  rodavam a partir de `mobile-app` ou `backend-core`.
+- A criação automática de change por plano aprovado agora preserva o backlink da sessão resolvido
+  pelo `transcript_path`/registry.
+- `vault-health` não exige `## Encerramento` de uma sessão ainda ativa; continua validando a ordem
+  completa quando a sessão está finalizada.
+
+### Migration
+
+- Rode `wendkeep init --force` para migrar hooks relativos instalados pela 0.31.0.
+- Rode `wendkeep sync-defs --reseed` para atualizar as skills wk-* em vaults existentes.
+- Changes antigas sem `spec_impact` continuam legíveis e são diagnosticadas como legadas; antes do
+  próximo archive, classifique-as explicitamente como `required` ou `none`.
+
 ## [0.31.0] — 2026-07-09
 
 ### Added — enforcement do loop a2 (o loop deixa de ser opcional na prática)

package/hooks/brain-inject.mjs

@@ -21,7 +21,7 @@ function processRouter(localeId) {
       '<wk_process>',
       'Spec-driven process (mandatory for any non-trivial task): INVOKE the wk-workflow Skill BEFORE editing any file.',
       '1. Plan: invoke the wk-brainstorming Skill (approved design) → wk-planning (task plan).',
-      '2. Record: `wendkeep change new <slug>` and FILL 08-Changes/<slug>/ — proposta.md (why/what), design.md (the approved approach), tarefas.md (the plan\'s tasks, `- [ ] N.N` with [req:ID]/[sensor:id]). Never leave the scaffold placeholders.',
+      '2. Record: `wendkeep change new <slug>` and FILL proposta/design/tasks. Resolve `spec_impact`: `required` needs `specs/<capability>/spec.md` + [req:ID]; `none` needs a reason. Never leave pending/placeholders.',
       '3. Implement: wk-tdd per task; tick `- [x]` as you finish. Something broke? wk-debugging.',
       '4. Close: `wendkeep verify` (+ `--deep` + the wk-verify Skill) → `wendkeep change archive`.',
       'NEVER `archive --force` on your own — a red gate means pending work; --force is the user\'s call, not yours. Dead end? `wendkeep change abandon`.',
@@ -32,7 +32,7 @@ function processRouter(localeId) {
     '<wk_process>',
     'Processo spec-driven (obrigatório em tarefa não-trivial): INVOQUE a Skill wk-workflow ANTES de editar qualquer arquivo.',
     '1. Planejar: invoque a Skill wk-brainstorming (design aprovado) → wk-planning (plano de tarefas).',
-    '2. Registrar: `wendkeep change new <slug>` e PREENCHA 08-Mudanças/<slug>/ — proposta.md (porquê/o quê), design.md (a abordagem aprovada), tarefas.md (as tarefas do plano, `- [ ] N.N` com [req:ID]/[sensor:id]). Nunca deixe os placeholders do scaffold.',
+    '2. Registrar: `wendkeep change new <slug>` e PREENCHA proposta/design/tarefas. Resolva `spec_impact`: `required` exige `specs/<capability>/spec.md` + [req:ID]; `none` exige justificativa. Nunca deixe pending/placeholders.',
     '3. Implementar: wk-tdd por tarefa; marque `- [x]` ao concluir. Quebrou algo? wk-debugging.',
     '4. Fechar: `wendkeep verify` (+ `--deep` + Skill wk-verify) → `wendkeep change archive`.',
     'PROIBIDO `archive --force` por conta própria — gate vermelho significa trabalho pendente; --force é decisão do usuário, não sua. Beco sem saída? `wendkeep change abandon`.',

package/hooks/change-core.mjs

@@ -14,9 +14,13 @@ export function changeDirRel(slug, vaultBase) {
   return join(getLocale(vaultBase).folders.changes, slug);
 }
 
-export function renderChangeScaffold({ slug, sessionRel, dateStr, locale = 'pt-BR' }) {
+export function renderChangeScaffold({ slug, sessionRel, dateStr, locale = 'pt-BR', simple = false }) {
   const en = locale === 'en';
   const source = sessionRel ? `\n  - "${wikilinkFromRel(sessionRel)}"` : ' []';
+  const impact = simple ? 'none' : 'pending';
+  const impactReason = simple
+    ? (en ? 'Simple change with no product-contract impact.' : 'Mudança simples sem impacto no contrato do produto.')
+    : '';
   const proposta = `---
 type: change
 status: active
@@ -26,6 +30,8 @@ cssclasses:
 tags:
   - mudanca
 source:${source}
+spec_impact: ${impact}
+spec_impact_reason: ${JSON.stringify(impactReason)}
 specs: []
 ---
 
@@ -96,13 +102,14 @@ export function newChange(vaultBase, slug, { sessionRel = '', dateStr, simple =
   const dir = join(vaultBase, loc.folders.changes, slug);
   const existed = existsSync(join(dir, 'proposta.md'));
   mkdirSync(dir, { recursive: true });
-  const files = renderChangeScaffold({ slug, sessionRel, dateStr, locale: loc.id });
+  const files = renderChangeScaffold({ slug, sessionRel, dateStr, locale: loc.id, simple });
   const write = (name, content) => {
     const f = join(dir, name);
     if (!existsSync(f)) writeFileSync(f, content, 'utf8');
   };
   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.
   if (!simple) {
     write('design.md', files.design);
@@ -291,6 +298,12 @@ export function archiveChange(vaultBase, slug, { gate = gateGreen, dateStr, adrN
   const loc = getLocale(vaultBase);
   const chDir = loc.folders.changes;
   const src = join(vaultBase, chDir, slug);
+  let sourceSessionRel = '';
+  try {
+    const proposal = readFileSync(join(src, 'proposta.md'), 'utf8');
+    const m = proposal.match(/\[\[((?:02-Sessões|02-Sessions)\/[^\]|]+?)(?:\|[^\]]+)?\]\]/);
+    if (m) sourceSessionRel = m[1].endsWith('.md') ? m[1] : `${m[1]}.md`;
+  } catch { /* sem source */ }
   const verdict = gate(src);
   if (!verdict.ok) return { ok: false, failing: verdict.failing || [] };
 
@@ -324,7 +337,9 @@ export function archiveChange(vaultBase, slug, { gate = gateGreen, dateStr, adrN
         ...res.warnings,
       ];
     }
-  } catch { /* promoção falhou — segue só com ADR */ }
+  } catch (error) {
+    return { ok: false, failing: [`falha ao promover specs: ${error.message}`] };
+  }
 
   let reqIds = [];
   try { reqIds = [...new Set(parseTasks(readFileSync(join(src, 'tarefas.md'), 'utf8')).map((t) => t.req).filter(Boolean))]; } catch { /* sem tarefas */ }
@@ -343,6 +358,17 @@ export function archiveChange(vaultBase, slug, { gate = gateGreen, dateStr, adrN
     writeFileSync(pp, c, 'utf8');
   } catch { /* proposta ilegível — segue */ }
 
+  // A sessão guardava o link da change ativa; após o move, reescreva para o caminho arquivado.
+  if (sourceSessionRel) {
+    try {
+      const sessionPath = join(vaultBase, sourceSessionRel);
+      const oldLink = wikilinkFromRel(join(chDir, slug, 'proposta'));
+      const archivedLink = wikilinkFromRel(join(destRel, 'proposta'));
+      const current = readFileSync(sessionPath, 'utf8');
+      if (current.includes(oldLink)) writeFileSync(sessionPath, current.replaceAll(oldLink, archivedLink), 'utf8');
+    } catch { /* backlink é reparo auxiliar; archive já está íntegro */ }
+  }
+
   // 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);

package/hooks/decision-capture.mjs

@@ -33,9 +33,20 @@ export function decisionKeyExists(dir, key) {
   return false;
 }
 
-// The AskUserQuestion tool_output reads: `... "Question"="chosen labels"  "Q2"="..."`.
+// Claude Code >= 2.1 returns `{ answers: { Question: choice } }` in tool_response.
+// Older releases expose a text tool_output: `... "Question"="chosen labels"  "Q2"="..."`.
 export function parseAnswers(output) {
   const map = {};
+  if (output && typeof output === 'object') {
+    const answers = output.answers && typeof output.answers === 'object'
+      ? output.answers
+      : output;
+    for (const [question, answer] of Object.entries(answers)) {
+      if (typeof answer === 'string') map[clean(question)] = clean(answer);
+      else if (Array.isArray(answer)) map[clean(question)] = answer.map(clean).filter(Boolean).join(',');
+    }
+    if (Object.keys(map).length) return map;
+  }
   const re = /"([^"]+)"\s*=\s*"([^"]*)"/g;
   let m;
   while ((m = re.exec(String(output || '')))) map[m[1].trim()] = m[2].trim();
@@ -172,7 +183,35 @@ export function captureDecision(vaultBase, input) {
   writeFileSync(filePath, buildDecisionCaptureNote({
     questions, answers, dateStr, startedAt: formatLocalIso(now), sessionRel, provider, localeId: loc.id, adrNum, contentKey,
   }), 'utf-8');
-  return { rel: toVaultRelative(vaultBase, filePath), skipped: false };
+  const rel = toVaultRelative(vaultBase, filePath);
+  if (sessionRel) {
+    try {
+      const sessionPath = join(vaultBase, sessionRel);
+      let session = readFileSync(sessionPath, 'utf8');
+      const wikilink = wikilinkFromRel(rel);
+      const link = `- ${wikilink}`;
+      if (!session.includes(wikilink)) {
+        const heading = '\n## Decisões geradas nesta sessão\n';
+        const at = session.indexOf(heading);
+        if (at !== -1) {
+          const bodyStart = at + heading.length;
+          const nextRel = session.slice(bodyStart).search(/\n## /);
+          const bodyEnd = nextRel === -1 ? session.length : bodyStart + nextRel;
+          const body = session.slice(bodyStart, bodyEnd)
+            .replace(/\n?Nenhuma decisão registrada ainda\.\s*/i, '\n')
+            .trim();
+          const merged = [body, link].filter(Boolean).join('\n');
+          session = `${session.slice(0, bodyStart)}\n${merged}\n\n${session.slice(bodyEnd).replace(/^\n+/, '')}`;
+        } else {
+          const anchor = session.indexOf('\n## Encerramento');
+          const section = `\n## Decisões geradas nesta sessão\n\n${link}\n`;
+          session = anchor === -1 ? `${session.trimEnd()}${section}` : `${session.slice(0, anchor).trimEnd()}${section}${session.slice(anchor)}`;
+        }
+        writeFileSync(sessionPath, session, 'utf8');
+      }
+    } catch { /* backlink auxiliar nunca derruba a captura */ }
+  }
+  return { rel, skipped: false };
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {

package/hooks/harness-doctor.mjs

@@ -3,7 +3,7 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { activeChange, parseTasks } from './change-core.mjs';
-import { parseRequirements, parseSpecsList, parseDelta, evaluateVerdict } from './spec-core.mjs';
+import { parseRequirements, parseSpecsList, parseDelta, evaluateVerdict, validateSpecImpact } from './spec-core.mjs';
 import { getLocale } from './locale.mjs';
 
 export function checkHarness(vaultBase, projectRoot) {
@@ -43,6 +43,9 @@ export function checkHarness(vaultBase, projectRoot) {
     let entries;
     try { entries = readdirSync(dir); } catch { continue; } // a file, not a change dir
     if (!entries.includes('proposta.md')) { errors.push(`change sem proposta.md: ${name}`); continue; }
+    const impact = validateSpecImpact(dir);
+    errors.push(...impact.errors.map((e) => `${name}: ${e}`));
+    warnings.push(...impact.warnings.map((w) => `${name}: ${w}`));
     if (name === active) {
       try {
         for (const cap of parseSpecsList(readFileSync(join(dir, 'proposta.md'), 'utf8'))) {

package/hooks/plan-capture.mjs

@@ -3,10 +3,20 @@
 // Code e o vault: quando o usuário APROVA um plano, o plano vira registro — anexado à change
 // ativa, ou uma change nova criada e preenchida a partir dele (proposta do Contexto, design do
 // corpo, tarefas dos checkboxes). Não depende de a LLM lembrar do processo. Rejeição = no-op.
-import { readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { formatDate, getVaultBase, readHookInput, slugify, writeHookOutput } from './obsidian-common.mjs';
+import {
+  findActiveSessionByTranscript,
+  formatDate,
+  getVaultBase,
+  readControl,
+  readHookInput,
+  slugify,
+  wikilinkFromRel,
+  writeHookOutput,
+} from './obsidian-common.mjs';
 import { activeChange, newChange } from './change-core.mjs';
 import { getLocale } from './locale.mjs';
 
@@ -17,8 +27,18 @@ export function extractPlan(input) {
   const tr = input?.tool_response ?? input?.toolResponse ?? '';
   const resp = typeof tr === 'string' ? tr : JSON.stringify(tr || '');
   if (/doesn'?t want to proceed|user rejected|rejected the plan/i.test(resp)) return null;
-  if (!/approved (your |the )?plan|Approved Plan/i.test(resp)) return null;
   const direct = input?.tool_input?.plan ?? input?.toolInput?.plan;
+  // Claude Code atual entrega o plano aprovado como objeto estruturado no PostToolUse.
+  // Esse evento só ocorre após sucesso; flags negativas explícitas continuam no-op.
+  if (tr && typeof tr === 'object') {
+    if (tr.approved === false || tr.rejected === true || tr.cancelled === true) return null;
+    const structured = tr.plan ?? direct;
+    if (structured && String(structured).trim()) return String(structured);
+    const structuredPath = tr.filePath ?? tr.planFilePath;
+    if (structuredPath) { try { return readFileSync(String(structuredPath), 'utf8'); } catch { /* inacessível */ } }
+    return null;
+  }
+  if (!/approved (your |the )?plan|Approved Plan/i.test(resp)) return null;
   if (direct && String(direct).trim()) return String(direct);
   const marker = resp.match(/## Approved Plan[^\n]*:\s*\n([\s\S]+)$/);
   if (marker && marker[1].trim()) return marker[1].trim();
@@ -27,6 +47,27 @@ export function extractPlan(input) {
   return null;
 }
 
+function planIndex(slug) {
+  return `---\ntype: plan-index\ntags:\n  - plano\n---\n\n# ${slug} — planos aprovados\n`;
+}
+
+export function persistApprovedPlan(dir, slug, rawNote, plan, dateStr) {
+  const hash = createHash('sha256').update(String(plan)).digest('hex').slice(0, 12);
+  const snapshotsDir = join(dir, 'planos');
+  mkdirSync(snapshotsDir, { recursive: true });
+  const snapshot = join(snapshotsDir, `${hash}.md`);
+  if (!existsSync(snapshot)) writeFileSync(snapshot, rawNote, 'utf8');
+
+  const indexPath = join(dir, 'plano-aprovado.md');
+  let index = existsSync(indexPath) ? readFileSync(indexPath, 'utf8') : planIndex(slug);
+  const entry = `- [[planos/${hash}|${dateStr} — ${hash}]]`;
+  if (!index.includes(`[[planos/${hash}|`)) {
+    index = `${index.trimEnd()}\n\n${entry}\n`;
+    writeFileSync(indexPath, index, 'utf8');
+  }
+  return { hash, snapshot };
+}
+
 export function planSlug(plan) {
   const h1 = String(plan || '').match(/^#\s+(.+)$/m);
   return h1 ? slugify(h1[1], 'plano-aprovado', 60) : 'plano-aprovado';
@@ -53,11 +94,15 @@ export function capturePlan(vaultBase, input) {
   const en = loc.id === 'en';
   const dateStr = formatDate(new Date());
   const rawNote = `---\ntype: plan\ndate: ${dateStr}\ntags:\n  - plano\n---\n\n${plan.trim()}\n`;
+  const transcriptPath = input?.transcript_path ?? input?.transcriptPath ?? '';
+  const sessionRel = findActiveSessionByTranscript(vaultBase, transcriptPath)?.session_file
+    || readControl(vaultBase).session_file
+    || '';
 
   const active = activeChange(vaultBase);
   if (active) {
     const dir = join(vaultBase, loc.folders.changes, active);
-    writeFileSync(join(dir, 'plano-aprovado.md'), rawNote, 'utf8');
+    persistApprovedPlan(dir, active, rawNote, plan, dateStr);
     return {
       slug: active, created: false,
       context: `<plan_captured>\n${en
@@ -67,9 +112,10 @@ export function capturePlan(vaultBase, input) {
   }
 
   const slug = planSlug(plan);
-  newChange(vaultBase, slug, { dateStr });
+  newChange(vaultBase, slug, { dateStr, sessionRel });
   const dir = join(vaultBase, loc.folders.changes, slug);
   const ctx = sectionBody(plan, ['Contexto', 'Context']) || plan.trim().split('\n').slice(0, 6).join('\n');
+  const source = sessionRel ? `\n  - "${wikilinkFromRel(sessionRel)}"` : ' []';
   writeFileSync(join(dir, 'proposta.md'), `---
 type: change
 status: active
@@ -78,7 +124,9 @@ cssclasses:
   - topic-change
 tags:
   - mudanca
-source: []
+source:${source}
+spec_impact: pending
+spec_impact_reason: ""
 specs: []
 ---
 
@@ -95,7 +143,7 @@ ${en ? 'See design.md and plano-aprovado.md (captured from the approved plan-mod
   writeFileSync(join(dir, 'design.md'), `# ${slug} — design\n\n${plan.trim()}\n`, 'utf8');
   const tasks = planTasks(plan);
   if (tasks.length) writeFileSync(join(dir, 'tarefas.md'), `# ${slug} — ${en ? 'tasks' : 'tarefas'}\n\n${tasks.join('\n')}\n`, 'utf8');
-  writeFileSync(join(dir, 'plano-aprovado.md'), rawNote, 'utf8');
+  persistApprovedPlan(dir, slug, rawNote, plan, dateStr);
   return {
     slug, created: true,
     context: `<plan_captured>\n${en
@@ -110,7 +158,11 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
     const r = capturePlan(getVaultBase(input), input);
     if (!r) { writeHookOutput({}); }
     else writeHookOutput({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: r.context } });
-  } catch {
-    writeHookOutput({});
+  } catch (error) {
+    process.stderr.write(`[wendkeep] plan-capture falhou: ${error.message}\n`);
+    writeHookOutput({ hookSpecificOutput: {
+      hookEventName: 'PostToolUse',
+      additionalContext: `<plan_capture_error>O plano aprovado não foi persistido: ${error.message}</plan_capture_error>`,
+    } });
   }
 }

package/hooks/spec-core.mjs

@@ -1,7 +1,7 @@
 // hooks/spec-core.mjs — living spec (07-Specs) + change delta merge (OpenSpec native).
 // Pure parsing/merge + promoteSpecs (fs). No import from change-core (avoids a cycle).
 import { createHash } from 'node:crypto';
-import { readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { ensureDir } from './obsidian-common.mjs';
 import { getLocale } from './locale.mjs';
@@ -87,6 +87,49 @@ export function parseSpecsList(propostaMd) {
   return [];
 }
 
+function yamlScalar(text, key) {
+  const m = String(text).match(new RegExp(`^${key}:\\s*(.*)$`, 'm'));
+  return m ? m[1].trim().replace(/^['"]|['"]$/g, '') : '';
+}
+
+export function parseSpecImpact(propostaMd) {
+  const text = String(propostaMd || '');
+  const status = yamlScalar(text, 'spec_impact') || yamlScalar(text, 'spec-impact');
+  const reason = yamlScalar(text, 'spec_impact_reason') || yamlScalar(text, 'spec-impact-reason');
+  return { status, reason };
+}
+
+export function validateSpecImpact(changeDir) {
+  let proposta = '';
+  try { proposta = readFileSync(join(changeDir, 'proposta.md'), 'utf8'); }
+  catch { return { ok: false, errors: ['proposta.md ausente'], warnings: [], status: '', listed: [], onDisk: [] }; }
+
+  const { status, reason } = parseSpecImpact(proposta);
+  const listed = parseSpecsList(proposta);
+  const onDisk = discoverSpecDeltas(changeDir);
+  const enforced = existsSync(join(changeDir, '.spec-impact-v1'));
+  const errors = [];
+  const warnings = [];
+
+  if (!status) {
+    if (enforced) errors.push('spec_impact ausente — classifique como required ou none');
+    else warnings.push('change legada sem spec_impact — migre para required ou none antes do próximo ciclo');
+    return { ok: errors.length === 0, errors, warnings, status: '', listed, onDisk, legacy: !enforced };
+  }
+  if (!['pending', 'required', 'none'].includes(status)) errors.push(`spec_impact inválido: ${status}`);
+  if (status === 'pending') errors.push('spec_impact pending — classifique o impacto antes de arquivar');
+  if (status === 'none') {
+    if (!reason) errors.push('spec_impact none exige justificativa em spec_impact_reason');
+    if (listed.length || onDisk.length) errors.push('spec_impact none contradiz specs/deltas declarados');
+  }
+  if (status === 'required') {
+    if (!listed.length) errors.push('spec_impact required exige ao menos uma capability em specs');
+    for (const cap of listed) if (!onDisk.includes(cap)) errors.push(`delta real ausente para capability ${cap}`);
+    for (const cap of onDisk) if (!listed.includes(cap)) errors.push(`delta ${cap} existe no disco mas não está listado em specs`);
+  }
+  return { ok: errors.length === 0, errors, warnings, status, reason, listed, onDisk, legacy: false };
+}
+
 // Um delta ainda no estado do scaffold (só o requisito "(nome)"/"(name)", nada removido) não é
 // contrato — a promoção o filtra. Um delta com REMOVED é sempre intenção real.
 export function isPlaceholderDelta(md) {
@@ -118,9 +161,11 @@ export function promoteSpecs(vaultBase, changeDir, specs, { changeWikilink, date
   const promoted = [];
   const warnings = [];
   for (const cap of specs) {
-    let delta;
-    try { delta = parseDelta(readFileSync(join(changeDir, 'specs', cap, 'spec.md'), 'utf8')); }
-    catch { warnings.push(`sem delta para ${cap}`); continue; }
+    let deltaMd;
+    try { deltaMd = readFileSync(join(changeDir, 'specs', cap, 'spec.md'), 'utf8'); }
+    catch { throw new Error(`delta ausente para ${cap}`); }
+    if (isPlaceholderDelta(deltaMd)) throw new Error(`delta placeholder para ${cap}`);
+    const delta = parseDelta(deltaMd);
     const livePath = join(vaultBase, specsDir, `${cap}.md`);
     let current = [];
     try { current = parseRequirements(readFileSync(livePath, 'utf8')); } catch { /* nova capability */ }

package/hooks/vault-health.mjs

@@ -71,14 +71,14 @@ function hasDefaultPending(content) {
     .some((line) => DEFAULT_PENDING_PATTERNS.some((pattern) => pattern.test(line.trim())));
 }
 
-function usageSectionIsPlaced(content) {
+function usageSectionIsPlaced(content, { active = false } = {}) {
   const usage = content.indexOf('\n## Uso de tokens e custos');
   if (usage === -1) return true;
   const changed = content.indexOf('\n## Arquivos criados ou alterados');
   const pending = content.indexOf('\n## Pendências');
   const closing = content.indexOf('\n## Encerramento');
-  if (pending === -1 || closing === -1) return false;
-  return usage < pending && usage < closing && (changed === -1 || usage > changed);
+  if (pending === -1 || (!active && closing === -1)) return false;
+  return usage < pending && (active || usage < closing) && (changed === -1 || usage > changed);
 }
 
 function linkedNotesFromSession(content) {
@@ -102,14 +102,15 @@ function checkSession({ vaultBase, sessionRel, control, registry }) {
     return { failures, warnings, metrics };
   }
 
-  const content = readFileSync(sessionPath, 'utf-8');
+  const content = readFileSync(sessionPath, 'utf-8');
+  const activeSession = control.status === 'active' && control.session_file === sessionRel;
   const duplicates = findDuplicateTurnMarkers(content);
   metrics.turnMarkers = (content.match(/<!-- (?:wk-turn|codex-turn):/g) || []).length;
   metrics.duplicateTurnMarkers = duplicates.length;
 
   if (duplicates.length) failures.push(`Marcadores de turno duplicados: ${duplicates.join(', ')}`);
   if (hasHeadingAfterClosing(content)) failures.push('Há headings/iterações após ## Encerramento.');
-  if (!usageSectionIsPlaced(content)) failures.push('## Uso de tokens e custos está fora da posição esperada.');
+  if (!usageSectionIsPlaced(content, { active: activeSession })) failures.push('## Uso de tokens e custos está fora da posição esperada.');
   if (hasDefaultPending(content)) warnings.push('Pendências ainda contém placeholders padrão.');
 
   const registryEntry = registry.sessions?.[control.session_id];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.31.0",
+  "version": "0.32.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/change.mjs

@@ -12,7 +12,7 @@ import {
   scaffoldPlaceholders,
 } from '../hooks/change-core.mjs';
 import { evaluateGate, requiredSensors } from '../hooks/sensors-core.mjs';
-import { evaluateVerdict, tasksHashOf, parseSpecsList, parseDelta, parseRequirements, applyDelta } from '../hooks/spec-core.mjs';
+import { evaluateVerdict, tasksHashOf, parseSpecsList, parseDelta, parseRequirements, applyDelta, validateSpecImpact } from '../hooks/spec-core.mjs';
 import { getNextAdrNumber, readControl } from '../hooks/obsidian-common.mjs';
 import { getLocale } from '../hooks/locale.mjs';
 
@@ -163,6 +163,9 @@ export function runChange(argv) {
       if (placeholders.length) {
         return { ok: false, failing: [`scaffold não preenchido (${placeholders.join('; ')}) — preencha proposta/design/tarefas antes de arquivar, ou \`wendkeep change abandon ${slug}\` se a change não vai adiante (--force não pula este check)`] };
       }
+      const impact = validateSpecImpact(dir);
+      for (const warning of impact.warnings) process.stderr.write(`aviso spec: ${warning}\n`);
+      if (!impact.ok) return { ok: false, failing: impact.errors };
       let tarefasMd = '';
       try { tarefasMd = readFileSync(join(dir, 'tarefas.md'), 'utf8'); } catch { /* no tasks */ }
       const tasks = parseTasks(tarefasMd);

package/src/init.mjs

@@ -15,6 +15,7 @@ import {
   mcpServerEntry,
   hookCommand,
   hookCommandLocal,
+  hookCommandLocalLegacy,
   deriveVaultDirName,
   selectableCompanions,
   resolveCompanions,
@@ -105,6 +106,16 @@ export function hookCommandFor(name, projectPath) {
   return hookCommand(name);
 }
 
+function localHookAvailable(name, projectPath) {
+  try {
+    return !!projectPath && existsSync(join(projectPath, 'node_modules', 'wendkeep', 'hooks', `${name}.mjs`));
+  } catch { return false; }
+}
+
+function localHookArg(name) {
+  return `${'${CLAUDE_PROJECT_DIR}'}/node_modules/wendkeep/hooks/${name}.mjs`;
+}
+
 export function mergeSettings(existing, { vaultPath, withMcp, force, companions = [], skipMcp = [], dotcontextHookLevel = 'full', projectPath = '' }) {
   const s = existing && typeof existing === 'object' ? { ...existing } : {};
   s.hooks = { ...(s.hooks || {}) };
@@ -120,19 +131,26 @@ export function mergeSettings(existing, { vaultPath, withMcp, force, companions
     ...companionHookSpecs(companions, { dotcontextHookLevel }),
   ].sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
   for (const h of allSpecs) {
-    const command = h.command ?? (h.preferLocal ? hookCommandFor(h.name, projectPath) : hookCommand(h.name));
+    const useLocal = !h.command && h.preferLocal && localHookAvailable(h.name, projectPath);
+    const command = h.command ?? (useLocal ? 'node' : hookCommand(h.name));
+    const args = useLocal ? [localHookArg(h.name)] : undefined;
     // Dual-recognition: um hook nomeado é reconhecido tanto na forma npx quanto na node-direta,
     // para que trocar a forma preferida (ou re-initar noutra máquina) nunca duplique o grupo.
-    const candidates = h.command ? [h.command] : [hookCommand(h.name), hookCommandLocal(h.name)];
+    const candidates = h.command ? [h.command] : [hookCommand(h.name), hookCommandLocal(h.name), hookCommandLocalLegacy(h.name)];
+    const ownsHook = (x) => candidates.includes(x.command)
+      || (x.command === 'node' && Array.isArray(x.args) && x.args[0] === localHookArg(h.name));
     const groups = Array.isArray(s.hooks[h.event]) ? [...s.hooks[h.event]] : [];
-    const owning = groups.find((g) => (g.hooks || []).some((x) => candidates.includes(x.command)));
+    const owning = groups.find((g) => (g.hooks || []).some(ownsHook));
     if (owning) {
       // Already wired: never add a duplicate group (the old `if (present && !force)` fell through
       // under --force and appended a second identical group). Under --force, refresh the managed
       // entry's fields in place — without disturbing any sibling hooks the user grouped with it.
-      if (force) {
-        const hk = owning.hooks.find((x) => candidates.includes(x.command));
+      const hk = owning.hooks.find(ownsHook);
+      const brokenRelative = hk?.command === hookCommandLocalLegacy(h.name);
+      if (force || brokenRelative) {
         hk.command = command;
+        if (args) hk.args = args;
+        else delete hk.args;
         hk.timeout = h.timeout;
         if (h.statusMessage) hk.statusMessage = h.statusMessage;
         if (h.matcher && (owning.hooks || []).length === 1) owning.matcher = h.matcher;
@@ -141,6 +159,7 @@ export function mergeSettings(existing, { vaultPath, withMcp, force, companions
       continue;
     }
     const entry = { type: 'command', command, timeout: h.timeout, statusMessage: h.statusMessage };
+    if (args) entry.args = args;
     const group = h.matcher ? { matcher: h.matcher, hooks: [entry] } : { hooks: [entry] };
     groups.push(group);
     s.hooks[h.event] = groups;
@@ -530,6 +549,8 @@ export async function runInit(argv) {
     log(M.mcpSkipped);
   }
 
+  log('  [!] ignore runtime do wendkeep no Git quando o vault for versionado: .brain/.change-*');
+
   // 4. Vault color system (.obsidian) -----------------------------------------
   if (args.noColors) {
     log(M.colorsSkipped);

package/src/skills-seed.mjs

@@ -31,6 +31,11 @@ vault cego. Exceção única: mudança trivial (typo, 1 linha).
    - \`tarefas.md\` — a lista de tarefas \`- [ ] N.N descrição\`.
    A mudança vira a *ativa* (ponteiro \`.brain/CURRENT_CHANGE.md\`) e é injetada no
    próximo SessionStart, então você retoma o trabalho em curso automaticamente.
+   Antes de implementar, resolva \`spec_impact\` na proposta:
+   - \`required\`: liste a capability em \`specs:\` e preencha
+     \`specs/<capability>/spec.md\` com ADDED/MODIFIED/REMOVED; ligue tarefas com \`[req:ID]\`.
+   - \`none\`: registre uma justificativa real em \`spec_impact_reason\`.
+   \`pending\` nunca é estado pronto para implementação ou archive.
 3. **Apply** — implemente cada tarefa de \`tarefas.md\` com disciplina **wk-tdd**
    (teste vermelho antes do código). Marque \`- [x]\` ao concluir. Declare nas tarefas:
    - \`[sensor:<id>]\` — a prova automatizada (roda no verify).
@@ -139,6 +144,7 @@ qualquer código.
 Antes de fechar o design, resolva cada zona cinza: decide com o usuário, ou registra como
 **assumption assinada** ("assumo X porque Y — corrija se errado"). Cinza declinado pelo
 usuário é *registrado*, não descartado no silêncio. Nada sai do design silenciosamente ambíguo.
+Declare também a capability e se o design tem \`spec_impact: required\` ou \`none\`.
 
 ## Tabela out-of-scope
 
@@ -170,6 +176,10 @@ Mapeie os arquivos: quais criar/modificar e a responsabilidade de cada um. Arqui
 mudam juntos ficam juntos; um arquivo, uma responsabilidade. É aqui que a decomposição
 trava.
 
+Resolva o contrato antes de decompor: \`spec_impact: required\` exige capability + delta real em
+\`specs/<capability>/spec.md\`; \`spec_impact: none\` exige justificativa. Cada comportamento do
+delta recebe ID e as tarefas correspondentes usam \`[req:ID]\`.
+
 ## Tarefas bite-sized (TDD)
 
 Cada tarefa termina num entregável testável de forma independente. Cada passo é uma ação
@@ -240,6 +250,9 @@ leaves the vault blind. Single exception: a trivial change (typo, one line).
 2. **Propose** — \`wendkeep change new <slug>\` scaffolds \`08-Changes/<slug>/\`
    (proposta/design/tarefas + a \`specs/\` delta). The change becomes *active* and is
    injected at the next SessionStart.
+   Before implementation, resolve \`spec_impact\`: \`required\` needs the capability listed in
+   \`specs:\` plus a real \`specs/<capability>/spec.md\` delta and \`[req:ID]\` links; \`none\`
+   needs a real \`spec_impact_reason\`. \`pending\` is never ready for implementation/archive.
 3. **Apply** — implement each task in tarefas.md with **wk-tdd** (red test first). Tag tasks:
    \`[sensor:<id>]\` (automated proof) and \`[req:<ID>]\` (the spec requirement it satisfies).
 4. **Verify** — \`wendkeep verify\` runs the sensors; then \`wendkeep verify --deep\` builds
@@ -310,6 +323,7 @@ Use it when the idea is still vague. Turn it into an approved design BEFORE writ
 ## Closure gate — no dangling ambiguity
 Resolve every gray area: decide with the user, or log a **signed-off assumption** ("assuming X
 because Y — correct me if wrong"). A declined gray area is recorded, not silently dropped.
+Also declare the capability and whether the design has \`spec_impact: required\` or \`none\`.
 
 ## Out-of-scope table
 List explicitly what the change does **not** do. Undeclared scope becomes creep.
@@ -331,6 +345,10 @@ Use it after an approved design. Produce a plan an engineer with no project cont
 Map the files: what to create/modify and each one's responsibility. Files that change together
 live together; one file, one responsibility.
 
+Resolve the contract first: \`spec_impact: required\` needs a capability and a real delta at
+\`specs/<capability>/spec.md\`; \`spec_impact: none\` needs a reason. Give each behaviour an ID
+and link the corresponding tasks with \`[req:ID]\`.
+
 ## Bite-sized tasks (TDD)
 Each task ends in an independently testable deliverable. Each step is a 2–5 min action:
 write the failing test (show code) → run and see it fail (exact command + expected) → minimal
@@ -434,6 +452,10 @@ comes from the package (freshness seal; edit a task later and the gate rejects i
 
 const PLAN_TEMPLATE_PT = `# Template — plano de tarefas (TDD, bite-sized)
 
+## Impacto em specs
+- \`spec_impact\`: \`required\` | \`none\`
+- Capability/delta: \`specs/<capability>/spec.md\` ou justificativa de \`none\`
+
 ## Arquivos
 - Criar: \`caminho/exato.mjs\`
 - Modificar: \`caminho/existente.mjs:120-140\`
@@ -457,6 +479,10 @@ tarefas (uma função é \`x()\` em toda parte). Cada tarefa termina num entreg
 
 const PLAN_TEMPLATE_EN = `# Template — task plan (TDD, bite-sized)
 
+## Spec impact
+- \`spec_impact\`: \`required\` | \`none\`
+- Capability/delta: \`specs/<capability>/spec.md\` or the \`none\` rationale
+
 ## Files
 - Create: \`exact/path.mjs\`
 - Modify: \`exact/existing.mjs:120-140\`

package/src/taxonomy.mjs

@@ -121,6 +121,10 @@ export function hookCommand(name) {
 // de segundos no Windows). Usada pelos hooks de ALTA FREQUÊNCIA (por prompt / por tool-call)
 // quando o projeto tem wendkeep instalado localmente; o init decide (hookCommandFor).
 export function hookCommandLocal(name) {
+  return `node "${'${CLAUDE_PROJECT_DIR}'}/node_modules/wendkeep/hooks/${name}.mjs"`;
+}
+
+export function hookCommandLocalLegacy(name) {
   return `node node_modules/wendkeep/hooks/${name}.mjs`;
 }