wendkeep 0.30.0 → 0.31.0

package/CHANGELOG.md

@@ -4,6 +4,71 @@ 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.31.0] — 2026-07-09
+
+### Added — enforcement do loop a2 (o loop deixa de ser opcional na prática)
+
+- **5 hooks de lifecycle novos**, wired por default pelo `wendkeep init` (invocação **node-direta**
+  `node node_modules/wendkeep/hooks/<name>.mjs` quando o pacote está instalado no projeto —
+  ~100-250ms vs segundos do npx no Windows; fallback npx):
+  - **`change-context`** (UserPromptSubmit) — re-injeta a change ativa (`<active_change_ping>`:
+    slug + tarefas abertas) SÓ quando o estado mudou desde a última injeção (hash em sentinela por
+    sessão). Sem change ativa: prompt com cara de tarefa ganha `<wk_skill_gate>` mandando invocar
+    a Skill wk-workflow ANTES de editar — 1x por sessão.
+  - **`change-warn`** (PostToolUse `Edit|Write|MultiEdit`) — edição de código sem change ativa
+    gera aviso 1x/sessão (nunca bloqueia; ignora vault/.claude/.agent/.brain e não-código).
+  - **`change-guard`** (PreToolUse `Bash`) — `wendkeep change archive --force` vindo do agente é
+    **negado** (deny; escape: `WENDKEEP_ALLOW_FORCE=1` no ambiente); `git commit` com change ativa
+    E (`--no-verify` OU sensor crítico vermelho) vira **ask** (o usuário decide). Fast-path sem
+    I/O para comandos comuns.
+  - **`change-nag`** (Stop) — change ativa com tarefas abertas bloqueia o encerramento 1x/sessão
+    cobrando fechamento honesto (done / verify / **ou informar a pendência ao usuário**).
+    Anti-loop absoluto via `stop_hook_active`.
+  - **`plan-capture`** (PostToolUse `ExitPlanMode`) — **a ponte determinística plan-mode → vault**:
+    plano aprovado no plan mode do Claude Code vira change no vault (proposta do Contexto, design
+    do corpo, tarefas dos checkboxes) ou anexa `plano-aprovado.md` à change ativa. Não depende de
+    a LLM lembrar do processo.
+- **`wendkeep change abandon [slug]`** — a saída legítima para change que não vai adiante: move
+  para `_arquivo/<data>-<slug>-abandonada` com `status: abandoned`, SEM ADR, SEM promoção de
+  specs; limpa o ponteiro só se era a ativa. Elimina o motivo real de `--force` em scaffold.
+- **`quickGateState(vaultBase)`** + sentinelas por sessão (`.brain/.change-*-<sid>`, GC >7 dias no
+  Stop) em change-core — fonte única do estado do gate para hooks e CLI.
+- **`wendkeep sync-defs --reseed`** — re-semeia as skills wk-* de `.brain/skills` com os seeds da
+  versão instalada (é como um vault existente recebe as descriptions/HARD-GATE novos).
+
+### Changed — gate endurecido + ativação da skill
+
+- **Verdict SEMPRE exigido no archive** (breaking-ish): sem `verdict.json` o archive bloqueia,
+  mesmo sem `[req:]` — `wendkeep verify --deep` grava o verdict trivial automático (1 comando).
+  Changes em andamento criadas antes de 0.31.0 precisam de um `verify --deep` antes do archive.
+- **G0 inescapável**: `--force` deixa de pular o check de scaffold — um scaffold cru NUNCA é
+  arquivável (era o buraco que mintou ADR falso em produção).
+- **`--force` e trivialidade rastreáveis**: ADR ganha `forced: true` (+ aviso ⚠️ no corpo) quando
+  `--force` pulou tarefa aberta, e `trivial: true` quando a change não declarou `[req:]`/`[sensor:]`.
+- **Promoção de specs = união frontmatter + disco**: o archive promove também os deltas REAIS
+  achados em `specs/*/spec.md` mesmo com `specs: []` na proposta (warning por cap não listada;
+  o `exemplo` placeholder do scaffold é filtrado). Fecha o buraco que deixava 07-Specs vazio com
+  delta preenchido no disco.
+- **Ativação da skill (paridade Superpowers)**: descriptions das wk-* reescritas com gatilhos
+  concretos ("Use SEMPRE que o usuário pedir para implementar/criar/corrigir/refatorar…
+  Invoque ANTES de editar qualquer arquivo"); `<HARD-GATE>` no corpo da wk-workflow; o
+  `<wk_process>` do brain-inject agora manda **invocar a Skill** (verbo de skill) e cita `abandon`.
+
+### Fixed
+
+- **Seções apagadas pelo Stop (classe de bug, visto em produção)**: qualquer seção inserida entre
+  `## Pendências` e `## Encerramento` era descartada pelo finalize (`replacePendingSection`
+  reconstruía o span inteiro) — atingia `## Subagents & Workflows` (frontmatter sobrevivia, corpo
+  sumia), `## Progresso do plano` e `## Mudanças`. Duas camadas: `upsertSection` agora ancora
+  ANTES de `## Pendências`, e o finalize preserva seções desconhecidas dentro do span. Notas
+  antigas se autocuram no próximo Stop/backfill (os dados persistem em `subagents/`).
+
+### Known limitation (aceita e documentada)
+
+- Hooks do mesmo evento rodam em **paralelo** no Claude Code: quando o `change-nag` bloqueia o
+  Stop, o `session-stop` já finalizou a nota — o turno de continuação não é logado nela
+  (recuperável via `session-backfill`/`import`; perda máx. de 1 turno, 1x por sessão).
+
 ## [0.30.0] — 2026-07-09
 
 ### Changed

package/bin/wendkeep.mjs

@@ -44,7 +44,8 @@ Usage:
 
   wendkeep doctor [--vault P]  Run a vault health check.
   wendkeep change <sub>        Change lifecycle: new [--simple] | list | show | status |
-                           done <id> | undone <id> | diff | archive [--force].
+                           done <id> | undone <id> | diff | archive [--force] | abandon [slug].
+                           archive exige verdict (rode verify --deep); abandon descarta sem ADR.
   wendkeep spec <sub>          Living specs: list | show <capability>.
   wendkeep sensors <sub>       list | add <id> "<command>" [--severity --type --report].
   wendkeep cost [opts]         Aggregate AI-coding spend across the vault's sessions.
@@ -70,6 +71,8 @@ Usage:
   wendkeep sync-defs [opts]    Copy versioned defs from the vault's .brain into the
                            project: .brain/agents/*.toml -> .codex/agents,
                            .brain/skills/<name> -> .claude/skills. --vault P --project P.
+                           --reseed re-semeia as skills wk-* com os seeds da versão instalada
+                           (sobrescreve edições manuais nas wk-*) antes de copiar.
   wendkeep --version           Print version.
   wendkeep --help              Show this help.
 `;

package/hooks/brain-inject.mjs

@@ -7,7 +7,7 @@ import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { getVaultBase, readHookInput, writeHookOutput } from './obsidian-common.mjs';
 import { brainDir } from './brain-core.mjs';
-import { buildActiveChangeInjection } from './change-core.mjs';
+import { buildActiveChangeInjection, changeCtxState, writeSentinel } from './change-core.mjs';
 import { buildLessonsInjection } from './lessons-core.mjs';
 import { getLocale } from './locale.mjs';
 
@@ -19,23 +19,23 @@ function processRouter(localeId) {
   if (localeId === 'en') {
     return [
       '<wk_process>',
-      'Spec-driven process (mandatory for any non-trivial task):',
-      '1. Plan: skill wk-brainstorming (approved design) → wk-planning (task plan).',
+      '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.',
       '3. Implement: wk-tdd per task; tick `- [x]` as you finish. Something broke? wk-debugging.',
-      '4. Close: `wendkeep verify` (+ `--deep` + skill wk-verify) → `wendkeep change archive`.',
-      'NEVER `archive --force` on your own — a red gate means pending work; --force is the user\'s call, not yours.',
+      '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`.',
       '</wk_process>',
     ].join('\n');
   }
   return [
     '<wk_process>',
-    'Processo spec-driven (obrigatório em tarefa não-trivial):',
-    '1. Planejar: skill wk-brainstorming (design aprovado) → wk-planning (plano de tarefas).',
+    '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.',
     '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.',
+    '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`.',
     '</wk_process>',
   ].join('\n');
 }
@@ -65,12 +65,19 @@ export function buildInjection(vaultBase) {
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   try {
     const input = readHookInput();
+    const vaultBase = getVaultBase(input);
     writeHookOutput({
       hookSpecificOutput: {
         hookEventName: 'SessionStart',
-        additionalContext: buildInjection(getVaultBase(input)),
+        additionalContext: buildInjection(vaultBase),
       },
     });
+    // Sentinela do change-context: a change ativa acabou de ser injetada aqui, então o hook de
+    // UserPromptSubmit não precisa re-pingar no 1º prompt. Bônus — nunca derruba a injeção.
+    try {
+      const st = changeCtxState(vaultBase);
+      if (st) writeSentinel(vaultBase, 'ctx', input.session_id || input.sessionId || '', st.hash);
+    } catch { /* sentinela é bônus */ }
   } catch (error) {
     process.stderr.write(`[brain] inject falhou: ${error.message}\n`);
     writeHookOutput({});

package/hooks/change-context.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// UserPromptSubmit hook. Dois papéis, ambos quiet-by-default (a maioria dos prompts não injeta nada):
+//   1. Com change ativa: re-injeta <active_change_ping> (slug + tarefas abertas) SÓ quando o
+//      estado mudou desde a última injeção (hash em sentinela por sessão) — o nudge do
+//      SessionStart dilui/compacta; este devolve o loop ao contexto no momento certo.
+//   2. Sem change ativa: prompt com cara de tarefa ganha <wk_skill_gate> mandando invocar a
+//      Skill wk-workflow ANTES de editar — 1x por sessão. É o empurrão de ativação da skill.
+// Fail-open; brain-inject grava a sentinela ctx no SessionStart para não duplicar no 1º prompt.
+import { pathToFileURL } from 'node:url';
+import { getVaultBase, readHookInput, writeHookOutput } from './obsidian-common.mjs';
+import { changeCtxState, readSentinel, writeSentinel } from './change-core.mjs';
+
+// Conservador de propósito: verbos de tarefa comuns (pt+en) + tamanho mínimo. Falso-negativo
+// custa só o nudge; falso-positivo em pergunta curta viraria ruído.
+const TASK_RE = /\b(implement\w*|cri[ae]\w*|corrig\w*|conserta\w*|refator\w*|adicion\w*|remov\w*|migr\w*|constru\w*|desenvolv\w*|fix\w*|add|build\w*|create\w*|refactor\w*|develop\w*|escrev\w*|write)\b/i;
+
+export function looksLikeTask(prompt) {
+  const p = String(prompt || '').trim();
+  return p.length >= 20 && TASK_RE.test(p);
+}
+
+// Retorna { context, hash? } quando há algo a injetar; null = silêncio.
+export function buildChangePing(vaultBase, sessionId, prompt = '') {
+  const st = changeCtxState(vaultBase);
+  if (st) {
+    if (readSentinel(vaultBase, 'ctx', sessionId) === st.hash) return null;
+    writeSentinel(vaultBase, 'ctx', sessionId, st.hash);
+    const lines = st.openTasks.map((t) => `- [ ] ${t.id} ${t.text}`);
+    const context = [
+      '<active_change_ping>',
+      `Mudança ativa: ${st.slug}${st.openTasks.length ? ` — tarefa(s) aberta(s):` : ' — sem tarefas abertas.'}`,
+      ...lines,
+      'Ao concluir uma tarefa: `wendkeep change done <id>`. Antes de arquivar: `wendkeep verify`.',
+      '</active_change_ping>',
+    ].join('\n');
+    return { context, hash: st.hash };
+  }
+  // Sem change ativa: gate de skill para prompt-tarefa, 1x por sessão.
+  if (!looksLikeTask(prompt)) return null;
+  if (readSentinel(vaultBase, 'gate', sessionId)) return null;
+  writeSentinel(vaultBase, 'gate', sessionId);
+  return {
+    context: [
+      '<wk_skill_gate>',
+      'Este pedido parece uma tarefa de código e NÃO há change ativa no vault. Antes de editar qualquer arquivo, invoque a Skill wk-workflow — ela orquestra o loop a2 (`wendkeep change new <slug>` → tarefas → verify → archive) e registra tudo no vault. Ignore apenas se a mudança for trivial (typo, 1 linha).',
+      '</wk_skill_gate>',
+    ].join('\n'),
+  };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const input = readHookInput();
+    const sid = input.session_id || input.sessionId || '';
+    const ping = buildChangePing(getVaultBase(input), sid, input.prompt || '');
+    if (!ping) { writeHookOutput({}); }
+    else writeHookOutput({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: ping.context } });
+  } catch {
+    writeHookOutput({});
+  }
+}

package/hooks/change-core.mjs

@@ -1,10 +1,10 @@
 // hooks/change-core.mjs
 // Native change/spec lifecycle in the vault (Pilar B). Vault-facing lib consumed by
 // the `wendkeep change` CLI (src/change.mjs) and the brain-inject hook. No external deps.
-import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { ensureDir, wikilinkFromRel, monthFolderRelFromDateStr } from './obsidian-common.mjs';
-import { parseSpecsList, promoteSpecs } from './spec-core.mjs';
+import { parseSpecsList, promoteSpecs, discoverSpecDeltas, tasksHashOf } from './spec-core.mjs';
 import { getLocale } from './locale.mjs';
 
 export const ARCHIVE_DIR = '_arquivo';
@@ -183,6 +183,79 @@ export function activeChangeLink(vaultBase) {
   return slug ? `Change ativa: [[${getLocale(vaultBase).folders.changes}/${slug}/proposta]]` : '';
 }
 
+// --- Estado rápido do gate + sentinelas por sessão (0.31.0) --------------------
+// Fonte única e barata (só leituras, tudo fail-open) do estado do gate, consumida pelos hooks
+// de lifecycle (change-guard/change-nag/change-context) e pelo CLI. null sem change ativa.
+export function quickGateState(vaultBase) {
+  const slug = activeChange(vaultBase);
+  if (!slug) return null;
+  const dir = join(vaultBase, getLocale(vaultBase).folders.changes, slug);
+  let tarefasMd = '';
+  try { tarefasMd = readFileSync(join(dir, 'tarefas.md'), 'utf8'); } catch { /* sem tarefas */ }
+  const openTasks = parseTasks(tarefasMd).filter((t) => !t.done).length;
+  let redCritical = false;
+  try {
+    const ev = JSON.parse(readFileSync(join(dir, 'evidencia.json'), 'utf8'));
+    redCritical = (Array.isArray(ev) ? ev : []).some((e) => e.status !== 'green' && (e.severity || 'critical') !== 'warning');
+  } catch { /* sem/ilegível = não conta contra o nudge */ }
+  let evidenceStale = false;
+  try {
+    const h = readFileSync(join(dir, '.evidence-hash'), 'utf8').trim();
+    evidenceStale = Boolean(h) && h !== tasksHashOf(tarefasMd);
+  } catch { /* nunca selada */ }
+  return { slug, openTasks, redCritical, evidenceStale, placeholders: scaffoldPlaceholders(dir).length };
+}
+
+// Sentinelas por sessão em .brain/ — memória "já avisei/injetei nesta sessão" dos hooks de
+// lifecycle. kind: 'ctx' | 'warn' | 'nag' | 'gate'. session_id sanitizado para nome de arquivo.
+const sanitizeSid = (sid) => String(sid || 'nosession').replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 64);
+
+export function sentinelPath(vaultBase, kind, sid) {
+  return join(vaultBase, '.brain', `.change-${kind}-${sanitizeSid(sid)}`);
+}
+
+export function readSentinel(vaultBase, kind, sid) {
+  try { return readFileSync(sentinelPath(vaultBase, kind, sid), 'utf8').trim(); } catch { return ''; }
+}
+
+export function writeSentinel(vaultBase, kind, sid, value = '1') {
+  try {
+    mkdirSync(join(vaultBase, '.brain'), { recursive: true });
+    writeFileSync(sentinelPath(vaultBase, kind, sid), value, 'utf8');
+  } catch { /* fail-open: pior caso = aviso repetido */ }
+}
+
+// Estado da change ativa para o ping do change-context: hash inclui o slug para que trocar de
+// change com tarefas idênticas ainda re-pingue.
+export function changeCtxState(vaultBase, { maxTasks = 5 } = {}) {
+  const slug = activeChange(vaultBase);
+  if (!slug) return null;
+  let md = '';
+  try { md = readFileSync(join(vaultBase, getLocale(vaultBase).folders.changes, slug, 'tarefas.md'), 'utf8'); } catch { /* sem tarefas */ }
+  return { slug, hash: tasksHashOf(`${slug}\n${md}`), openTasks: parseTasks(md).filter((t) => !t.done).slice(0, maxTasks) };
+}
+
+// GC das sentinelas (>7 dias) — seleção pura separada da execução (testável sem depender de
+// unlink funcionar no sandbox). Roda no finalize do session-stop, fail-quiet.
+const SENTINEL_RE = /^\.change-(?:ctx|warn|nag|gate)-/;
+
+export function staleSentinelNames(entries, now = Date.now(), maxAgeMs = 7 * 86400000) {
+  return (entries || []).filter((e) => SENTINEL_RE.test(e.name) && now - e.mtimeMs > maxAgeMs).map((e) => e.name);
+}
+
+export function pruneChangeSentinels(vaultBase, { now = Date.now() } = {}) {
+  const dir = join(vaultBase, '.brain');
+  let entries = [];
+  try {
+    entries = readdirSync(dir)
+      .map((name) => { try { return { name, mtimeMs: statSync(join(dir, name)).mtimeMs }; } catch { return null; } })
+      .filter(Boolean);
+  } catch { return []; }
+  const stale = staleSentinelNames(entries, now);
+  for (const name of stale) { try { unlinkSync(join(dir, name)); } catch { /* fail-quiet */ } }
+  return stale;
+}
+
 // Append fix tasks for surviving mutants to a change's tarefas.md (Wave B). Deduped by
 // file:line, numbered M.<n> continuing from any existing fix tasks. Returns count added.
 export function appendFixTasks(changeDir, mutants, sensorId) {
@@ -214,7 +287,7 @@ export function gateGreen() {
   return { ok: true, failing: [] };
 }
 
-export function archiveChange(vaultBase, slug, { gate = gateGreen, dateStr, adrNum }) {
+export function archiveChange(vaultBase, slug, { gate = gateGreen, dateStr, adrNum, adrFlags = {} }) {
   const loc = getLocale(vaultBase);
   const chDir = loc.folders.changes;
   const src = join(vaultBase, chDir, slug);
@@ -233,16 +306,25 @@ export function archiveChange(vaultBase, slug, { gate = gateGreen, dateStr, adrN
   }
 
   // Promote spec deltas into the living 07-Specs BEFORE moving (deltas live in src).
+  // UNIÃO frontmatter + disco (0.31.0): o scaffold deixa `specs: []`, então um delta real
+  // preenchido em specs/<cap>/ mas não listado era silenciosamente ignorado. Deltas ainda em
+  // placeholder (o `exemplo` do scaffold) são filtrados por discoverSpecDeltas.
   let promoted = [];
   let specWarnings = [];
   try {
-    const specs = parseSpecsList(readFileSync(join(src, 'proposta.md'), 'utf8'));
-    if (specs.length) {
-      const res = promoteSpecs(vaultBase, src, specs, { changeWikilink, dateStr });
+    let listed = [];
+    try { listed = parseSpecsList(readFileSync(join(src, 'proposta.md'), 'utf8')); } catch { /* proposta ilegível */ }
+    const onDisk = discoverSpecDeltas(src);
+    const union = [...new Set([...listed, ...onDisk])];
+    if (union.length) {
+      const res = promoteSpecs(vaultBase, src, union, { changeWikilink, dateStr });
       promoted = res.promoted;
-      specWarnings = res.warnings;
+      specWarnings = [
+        ...onDisk.filter((c) => !listed.includes(c)).map((c) => `spec no disco não listada no frontmatter da proposta: ${c} — promovida assim mesmo`),
+        ...res.warnings,
+      ];
     }
-  } catch { /* proposta ilegível — segue só com ADR */ }
+  } catch { /* promoção falhou — segue só com ADR */ }
 
   let reqIds = [];
   try { reqIds = [...new Set(parseTasks(readFileSync(join(src, 'tarefas.md'), 'utf8')).map((t) => t.req).filter(Boolean))]; } catch { /* sem tarefas */ }
@@ -271,10 +353,13 @@ export function archiveChange(vaultBase, slug, { gate = gateGreen, dateStr, adrN
     ? `\n\nCapabilities: ${promoted.map((c) => wikilinkFromRel(join(loc.folders.specs, c))).join(', ')}.`
     : '';
   const reqLine = reqIds.length ? `\n\nRequisitos: ${reqIds.join(', ')}.` : '';
+  // Rastro auditável (0.31.0): um archive forçado ou sem prova declarada fica marcado no ADR.
+  const flagLines = `${adrFlags.forced ? '\nforced: true' : ''}${adrFlags.trivial ? '\ntrivial: true' : ''}`;
+  const forcedNote = adrFlags.forced ? '\n\n> ⚠️ Arquivada com --force — havia tarefa(s) aberta(s) pulada(s) no gate.' : '';
   writeFileSync(join(vaultBase, adrRel), `---
 type: decision
 status: accepted
-date: ${dateStr}
+date: ${dateStr}${flagLines}
 cssclasses:
   - topic-decision
 tags:
@@ -285,7 +370,7 @@ tags:
 
 ## Decisão
 
-Mudança ${changeWikilink} concluída e arquivada.${capLine}${reqLine}
+Mudança ${changeWikilink} concluída e arquivada.${capLine}${reqLine}${forcedNote}
 `, 'utf8');
 
   // Only clear the pointer when the archived change IS the active one — archiving some other
@@ -293,3 +378,23 @@ Mudança ${changeWikilink} concluída e arquivada.${capLine}${reqLine}
   if (activeChange(vaultBase) === slug) clearActiveChange(vaultBase);
   return { ok: true, failing: [], archivedRel: destRel, adrRel, promoted, specWarnings };
 }
+
+// Abandono (0.31.0): a saída legítima para uma change que não vai adiante — o que antes só o
+// `archive --force` "resolvia", minting um ADR falso. Sem ADR, sem promoteSpecs (abandono não é
+// decisão arquitetural nem promove contrato); move para _arquivo com sufixo -abandonada.
+export function abandonChange(vaultBase, slug, { dateStr }) {
+  const chDir = getLocale(vaultBase).folders.changes;
+  const src = join(vaultBase, chDir, slug);
+  if (!existsSync(join(src, 'proposta.md'))) return { ok: false, failing: [`change não encontrada: ${slug}`] };
+  const destRel = join(chDir, ARCHIVE_DIR, `${dateStr}-${slug}-abandonada`);
+  const destAbs = join(vaultBase, destRel);
+  if (existsSync(destAbs)) return { ok: false, failing: [`destino já existe: ${destRel}`] };
+  ensureDir(join(vaultBase, chDir, ARCHIVE_DIR));
+  try { renameSync(src, destAbs); } catch (e) { return { ok: false, failing: [`falha ao mover: ${e.message}`] }; }
+  try {
+    const pp = join(destAbs, 'proposta.md');
+    writeFileSync(pp, readFileSync(pp, 'utf8').replace(/^status:\s*active\s*$/m, 'status: abandoned'), 'utf8');
+  } catch { /* proposta sem frontmatter — segue */ }
+  if (activeChange(vaultBase) === slug) clearActiveChange(vaultBase);
+  return { ok: true, failing: [], archivedRel: destRel };
+}

package/hooks/change-guard.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// PreToolUse hook (matcher: Bash). O gate mecânico do loop a2 no ponto de execução:
+//   R1 — `wendkeep|wk change archive --force` vindo do AGENTE é negado (deny). Gate vermelho
+//        significa trabalho pendente; --force é decisão do usuário (escape: WENDKEEP_ALLOW_FORCE=1
+//        no ambiente do processo — env inline no texto do comando NÃO conta).
+//   R2 — `git commit` com change ativa E (--no-verify OU sensor crítico vermelho) vira `ask`
+//        (o usuário decide com 1 clique; falso-positivo custa pouco).
+// Fast-path: comando sem wendkeep/wk/git sai sem NENHUM I/O. Fail-open.
+import { pathToFileURL } from 'node:url';
+import { getVaultBase, readHookInput, writeHookOutput } from './obsidian-common.mjs';
+import { activeChange, quickGateState } from './change-core.mjs';
+
+const FORCE_RE = /\b(?:wendkeep|wk)\s+change\s+archive\b[^|&;\n]*--force\b/;
+const GIT_SEG_RE = /(^|&&|;|\|)\s*git\b[^|&;]*\bcommit\b/;
+const FAST_RE = /\b(?:wendkeep|wk|git)\b/;
+
+export function guardDecision(command, { vaultBase, env = process.env } = {}) {
+  const cmd = String(command || '');
+  if (!FAST_RE.test(cmd)) return null; // fast-path: zero I/O para o caso comum
+
+  // R1: archive --force — puro regex, ainda sem I/O. Reason fala com o AGENTE (deny).
+  if (FORCE_RE.test(cmd)) {
+    if (env.WENDKEEP_ALLOW_FORCE === '1') return null;
+    return {
+      permissionDecision: 'deny',
+      permissionDecisionReason: '`change archive --force` é decisão do usuário, não sua. Gate vermelho = trabalho pendente: rode `wendkeep change status` e conclua as tarefas, ou `wendkeep change abandon <slug>` se a change não vai adiante. Se o usuário pediu o force explicitamente, peça a ele para rodar com WENDKEEP_ALLOW_FORCE=1.',
+    };
+  }
+
+  // R2: git commit — 1ª leitura de fs só acontece aqui. Reason fala com o USUÁRIO (ask).
+  const m = cmd.match(GIT_SEG_RE);
+  if (m) {
+    const slug = activeChange(vaultBase);
+    if (!slug) return null;
+    const seg = cmd.slice(m.index + m[1].length).split(/&&|;|\|/)[0];
+    const noVerify = /\s--no-verify\b/.test(seg);
+    const gate = noVerify ? null : quickGateState(vaultBase);
+    if (noVerify || (gate && gate.redCritical)) {
+      return {
+        permissionDecision: 'ask',
+        permissionDecisionReason: noVerify
+          ? `git commit --no-verify com a change "${slug}" ativa — commitar pulando os hooks?`
+          : `A change ativa "${slug}" tem sensor crítico vermelho (wendkeep verify falhou). Commitar mesmo assim?`,
+      };
+    }
+  }
+  return null;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const input = readHookInput();
+    const d = guardDecision(input.tool_input?.command, { vaultBase: getVaultBase(input) });
+    if (d) writeHookOutput({ hookSpecificOutput: { hookEventName: 'PreToolUse', ...d } });
+    // allow implícito: exit 0 sem output
+  } catch {
+    writeHookOutput({}); // fail-open = allow
+  }
+}

package/hooks/change-nag.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// Stop hook. Se a change ativa tem tarefas abertas quando o agente tenta encerrar o turno,
+// bloqueia UMA vez por sessão cobrando fechamento honesto: marcar done, rodar verify, OU
+// informar a pendência ao usuário e encerrar (a saída honesta é obrigatória no reason — sem
+// ela o modelo é incentivado a marcar done falso só para conseguir parar).
+// Anti-loop absoluto: stop_hook_active é o PRIMEIRO check, antes de qualquer I/O.
+import { pathToFileURL } from 'node:url';
+import { getVaultBase, readHookInput, writeHookOutput } from './obsidian-common.mjs';
+import { quickGateState, readSentinel, writeSentinel } from './change-core.mjs';
+
+export function nagDecision(input, vaultBase) {
+  if (input && input.stop_hook_active) return null; // anti-loop: sempre primeiro
+  const gate = quickGateState(vaultBase);
+  if (!gate || !gate.openTasks) return null;
+  const sid = input?.session_id || input?.sessionId || '';
+  if (readSentinel(vaultBase, 'nag', sid)) return null;
+  writeSentinel(vaultBase, 'nag', sid);
+  return {
+    decision: 'block',
+    reason: `A change ativa "${gate.slug}" tem ${gate.openTasks} tarefa(s) aberta(s). Antes de encerrar: marque as concluídas com \`wendkeep change done <id>\`, rode \`wendkeep verify\`, ou informe a pendência ao usuário e encerre.`,
+  };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const input = readHookInput();
+    writeHookOutput(nagDecision(input, getVaultBase(input)) || {});
+  } catch {
+    writeHookOutput({});
+  }
+}

package/hooks/change-warn.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+// PostToolUse hook (matcher: Edit|Write|MultiEdit). Quando o agente edita CÓDIGO sem change
+// ativa, avisa UMA vez por sessão que trabalho não-trivial deve rotear pelo loop a2. Nunca
+// bloqueia — mudança trivial pode seguir. Ignora edições no vault e em .claude/.agent/.brain.
+import { isAbsolute, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { getVaultBase, readHookInput, writeHookOutput } from './obsidian-common.mjs';
+import { activeChange, readSentinel, writeSentinel } from './change-core.mjs';
+
+const CODE_EXT = /\.(ts|tsx|js|jsx|mjs|cjs|py|prisma|sql|go|rs|java|cs)$/i;
+
+export function isCodeFile(p) {
+  return CODE_EXT.test(String(p || '').replace(/\\/g, '/'));
+}
+
+const norm = (p) => String(p || '').replace(/\\/g, '/');
+
+// Retorna o additionalContext do aviso, ou null (caso comum).
+export function warnDecision(filePath, { vaultBase, cwd = '.', sessionId = '' } = {}) {
+  if (!filePath || !isCodeFile(filePath)) return null;
+  if (activeChange(vaultBase)) return null;
+  const abs = norm(isAbsolute(filePath) ? filePath : resolve(cwd, filePath));
+  // Dentro do vault (NTFS é case-insensitive) ou em dirs de config de agente: não é código do projeto.
+  if (abs.toLowerCase().startsWith(`${norm(resolve(vaultBase)).toLowerCase()}/`)) return null;
+  if (/\/(\.claude|\.agent|\.brain)\//.test(`${abs}/`)) return null;
+  if (readSentinel(vaultBase, 'warn', sessionId)) return null;
+  writeSentinel(vaultBase, 'warn', sessionId);
+  return [
+    '<change_warn>',
+    `Você editou código (${filePath}) sem change ativa. Para trabalho não-trivial, roteie pelo processo: \`wendkeep change new <slug>\` e preencha proposta/design/tarefas (skill wk-workflow). Ignore se for um ajuste trivial — este aviso não repete nesta sessão.`,
+    '</change_warn>',
+  ].join('\n');
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const input = readHookInput();
+    const warn = warnDecision(input.tool_input?.file_path, {
+      vaultBase: getVaultBase(input),
+      cwd: input.cwd || '.',
+      sessionId: input.session_id || input.sessionId || '',
+    });
+    if (!warn) { writeHookOutput({}); }
+    else writeHookOutput({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: warn } });
+  } catch {
+    writeHookOutput({});
+  }
+}

package/hooks/plan-capture.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// PostToolUse hook (matcher: ExitPlanMode). A ponte determinística entre o plan mode do Claude
+// 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 { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { formatDate, getVaultBase, readHookInput, slugify, writeHookOutput } from './obsidian-common.mjs';
+import { activeChange, newChange } from './change-core.mjs';
+import { getLocale } from './locale.mjs';
+
+// O plano aprovado chega por um de três canais, conforme a versão do Claude Code:
+// tool_input.plan (legado), o bloco "## Approved Plan" do tool_response, ou o arquivo de plano
+// citado em "saved to: <path>". Rejeição (ou ausência de sinal de aprovação) → null.
+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;
+  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();
+  const path = resp.match(/saved to:\s*([^\n]+\.md)/i);
+  if (path) { try { return readFileSync(path[1].trim(), 'utf8'); } catch { /* arquivo inacessível */ } }
+  return null;
+}
+
+export function planSlug(plan) {
+  const h1 = String(plan || '').match(/^#\s+(.+)$/m);
+  return h1 ? slugify(h1[1], 'plano-aprovado', 60) : 'plano-aprovado';
+}
+
+function sectionBody(plan, headings) {
+  for (const h of headings) {
+    const m = String(plan).match(new RegExp(`^##\\s+${h}\\s*\\n([\\s\\S]*?)(?=\\n##\\s|$)`, 'm'));
+    if (m && m[1].trim()) return m[1].trim();
+  }
+  return '';
+}
+
+// Checkboxes do plano viram tarefas numeradas 1.N (estado [x] preservado). [] quando não há.
+export function planTasks(plan) {
+  const boxes = [...String(plan || '').matchAll(/^\s*-\s+\[( |x)\]\s+(.+)$/gm)];
+  return boxes.map((m, i) => `- [${m[1]}] 1.${i + 1} ${m[2].trim()}`);
+}
+
+export function capturePlan(vaultBase, input) {
+  const plan = extractPlan(input);
+  if (!plan) return null;
+  const loc = getLocale(vaultBase);
+  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 active = activeChange(vaultBase);
+  if (active) {
+    const dir = join(vaultBase, loc.folders.changes, active);
+    writeFileSync(join(dir, 'plano-aprovado.md'), rawNote, 'utf8');
+    return {
+      slug: active, created: false,
+      context: `<plan_captured>\n${en
+        ? `Approved plan attached to the active change "${active}" (plano-aprovado.md). Sync tarefas.md with the plan's tasks.`
+        : `Plano aprovado anexado à change ativa "${active}" (plano-aprovado.md). Sincronize tarefas.md com as tarefas do plano.`}\n</plan_captured>`,
+    };
+  }
+
+  const slug = planSlug(plan);
+  newChange(vaultBase, slug, { dateStr });
+  const dir = join(vaultBase, loc.folders.changes, slug);
+  const ctx = sectionBody(plan, ['Contexto', 'Context']) || plan.trim().split('\n').slice(0, 6).join('\n');
+  writeFileSync(join(dir, 'proposta.md'), `---
+type: change
+status: active
+date: ${dateStr}
+cssclasses:
+  - topic-change
+tags:
+  - mudanca
+source: []
+specs: []
+---
+
+# ${slug}
+
+${en ? '## Why' : '## Por quê'}
+
+${ctx}
+
+${en ? '## What changes' : '## O que muda'}
+
+${en ? 'See design.md and plano-aprovado.md (captured from the approved plan-mode plan).' : 'Ver design.md e plano-aprovado.md (capturados do plano aprovado no plan mode).'}
+`, 'utf8');
+  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');
+  return {
+    slug, created: true,
+    context: `<plan_captured>\n${en
+      ? `Approved plan recorded in the vault: change "${slug}" created and set active (${loc.folders.changes}/${slug}/). Review tarefas.md${tasks.length ? '' : ' — the plan had no checkboxes, fill the tasks'} and follow the a2 loop (wk-tdd per task, \`wendkeep change done <id>\`, \`wendkeep verify\`).`
+      : `Plano aprovado — change "${slug}" registrada no vault e ativa (${loc.folders.changes}/${slug}/). Revise tarefas.md${tasks.length ? '' : ' — o plano não tinha checkboxes, preencha as tarefas'} e siga o loop a2 (wk-tdd por tarefa, \`wendkeep change done <id>\`, \`wendkeep verify\`).`}\n</plan_captured>`,
+  };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const input = readHookInput();
+    const r = capturePlan(getVaultBase(input), input);
+    if (!r) { writeHookOutput({}); }
+    else writeHookOutput({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: r.context } });
+  } catch {
+    writeHookOutput({});
+  }
+}

package/hooks/session-stop.mjs

@@ -6,7 +6,7 @@ import { pathToFileURL } from 'url';
 import { createLinkedNotes } from './linked-notes.mjs';
 import { addUsage, costBreakdown, emptyTokenUsage, normalizeClaudeUsage, normalizeCodexUsage, priceForModel, updateSessionUsage } from './token-usage.mjs';
 import { buildBrainDigest, buildBrainIndex } from './brain-core.mjs';
-import { activeChangeLink } from './change-core.mjs';
+import { activeChangeLink, pruneChangeSentinels } from './change-core.mjs';
 import { getLocale } from './locale.mjs';
 import { upsertSubagentUsage } from './subagent-usage.mjs';
 import {
@@ -855,12 +855,19 @@ function replacePendingSection(content, pending) {
   const end = content.indexOf(closingMarker, start + marker.length);
   if (end === -1) return content;
 
+  // Preserva seções que outros writers inseriram dentro do span (## Subagents & Workflows,
+  // ## Progresso do plano, ## Mudanças…) — só o texto das Pendências em si é regenerado.
+  const span = content.slice(start + marker.length, end);
+  const innerIdx = span.indexOf('\n## ');
+  const preserved = innerIdx === -1 ? '' : span.slice(innerIdx).trimEnd();
+
   return [
     content.slice(0, start).trimEnd(),
     '',
     '## Pendências',
     '',
     formatPendingSection(pending),
+    ...(preserved ? [preserved] : []),
     content.slice(end),
   ].join('\n');
 }
@@ -1135,6 +1142,9 @@ function main() {
     process.stderr.write(`[wendkeep] brain index/digest falhou: ${error.message}\n`);
   }
 
+  // GC das sentinelas dos hooks de lifecycle (>7 dias) — fail-quiet, nunca derruba o Stop.
+  try { pruneChangeSentinels(vaultBase); } catch { /* bônus */ }
+
   pingObsidianVault(input.obsidian_api_key);
   writeHookOutput({});
 }

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, writeFileSync } from 'node:fs';
+import { 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,30 @@ export function parseSpecsList(propostaMd) {
   return [];
 }
 
+// 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) {
+  const d = parseDelta(md);
+  if (d.removed.length) return false;
+  const all = [...d.added, ...d.modified];
+  if (!all.length) return true;
+  return all.every((r) => /^\((?:nome|name)\)$/.test(r.name));
+}
+
+// Capabilities com delta REAL no disco (<change>/specs/<cap>/spec.md), independente do
+// frontmatter `specs:` da proposta — o scaffold deixa `specs: []` e o buraco engolia deltas
+// preenchidos mas não listados (visto em produção: 07-Specs vazio com delta real no disco).
+export function discoverSpecDeltas(changeDir) {
+  let names = [];
+  try { names = readdirSync(join(changeDir, 'specs')); } catch { return []; }
+  const caps = [];
+  for (const cap of names) {
+    try { if (!isPlaceholderDelta(readFileSync(join(changeDir, 'specs', cap, 'spec.md'), 'utf8'))) caps.push(cap); }
+    catch { /* sem spec.md */ }
+  }
+  return caps;
+}
+
 // Merge each capability's delta (in the change) into the living spec in 07-Specs.
 export function promoteSpecs(vaultBase, changeDir, specs, { changeWikilink, dateStr } = {}) {
   const loc = getLocale(vaultBase);

package/hooks/subagent-usage.mjs

@@ -208,7 +208,9 @@ function upsertSection(content, heading, body) {
   const esc = heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
   const re = new RegExp(`${esc}\\n[\\s\\S]*?(?=\\n## |$)`);
   if (re.test(content)) return content.replace(re, `${body}\n`);
-  for (const anchor of ['\n## Encerramento', '\n## Issues Linear', '\n## Pendências']) {
+  // Âncora ANTES de '## Pendências': o finalize do Stop reescreve o span Pendências→Encerramento
+  // inteiro, então qualquer seção inserida lá dentro seria apagada (visto em produção).
+  for (const anchor of ['\n## Pendências', '\n## Issues Linear', '\n## Encerramento']) {
     const i = content.indexOf(anchor);
     if (i >= 0) return `${content.slice(0, i)}\n\n${body}\n${content.slice(i)}`;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.30.0",
+  "version": "0.31.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

@@ -8,6 +8,7 @@ import {
   parseTasks,
   setTaskDone,
   archiveChange,
+  abandonChange,
   scaffoldPlaceholders,
 } from '../hooks/change-core.mjs';
 import { evaluateGate, requiredSensors } from '../hooks/sensors-core.mjs';
@@ -104,8 +105,8 @@ export function runChange(argv) {
     const reqIds = [...new Set(tasks.map((t) => t.req).filter(Boolean))];
     let verdict = null;
     try { verdict = JSON.parse(readFileSync(join(dir, 'verdict.json'), 'utf8')); } catch { /* sem verdict */ }
-    if (!reqIds.length) process.stdout.write('verdict: não exigido (sem [req:])\n');
-    else if (!verdict) process.stdout.write('verdict: ausente — rode `wendkeep verify --deep` + wk-verify\n');
+    if (!verdict) process.stdout.write(`verdict: ausente — rode \`wendkeep verify --deep\`${reqIds.length ? ' + wk-verify' : ' (verdict trivial automático)'}\n`);
+    else if (!reqIds.length) process.stdout.write(`verdict: ${verdict.ok === true ? 'ok (trivial)' : 'não-ok — re-verifique'}\n`);
     else {
       const v = evaluateVerdict(verdict, reqIds, { tasksHash: tasksHashOf(tarefasMd) });
       process.stdout.write(`verdict: ${v.ok ? 'ok' : v.stale ? 'stale — re-verifique' : `incompleto: falta ${v.missing.join(', ')}`}\n`);
@@ -156,11 +157,11 @@ export function runChange(argv) {
     // Real gate (Pilar C): every sensor a task declared must be green in evidencia.json.
     const gate = (dir) => {
       // G0: um scaffold nunca preenchido não é uma mudança concluída — arquivar geraria um
-      // ADR falso. Bloqueia antes de qualquer outro check (o --force ainda escapa, mas a
-      // regra injetada proíbe o agente de usá-lo sem o usuário pedir).
+      // ADR falso. INESCAPÁVEL desde 0.31.0 (--force não pula — visto em produção: change
+      // 100% placeholder arquivada via --force mintou ADR falso). Saída legítima: abandon.
       const placeholders = scaffoldPlaceholders(dir);
-      if (placeholders.length && !rest.includes('--force')) {
-        return { ok: false, failing: [`scaffold não preenchido (${placeholders.join('; ')}) — preencha proposta/design/tarefas com o design e o plano antes de arquivar`] };
+      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)`] };
       }
       let tarefasMd = '';
       try { tarefasMd = readFileSync(join(dir, 'tarefas.md'), 'utf8'); } catch { /* no tasks */ }
@@ -185,17 +186,38 @@ export function runChange(argv) {
       try { evidence = JSON.parse(readFileSync(join(dir, 'evidencia.json'), 'utf8')); } catch { /* no evidence */ }
       const s = evaluateGate(evidence, required);
       if (!s.ok) return s;
-      // Independent verdict (Wave A): required only when the change declares [req:] tasks.
+      // Verdict SEMPRE exigido (0.31.0) — a exigência universal vive AQUI no gate; a semântica
+      // reqless→ok de evaluateVerdict (spec-core) não muda porque `verify --deep` e `change
+      // status` dependem dela. Change sem [req:] destrava com o auto-verdict do verify --deep.
       let verdict = null;
       try { verdict = JSON.parse(readFileSync(join(dir, 'verdict.json'), 'utf8')); } catch { /* none */ }
-      const v = evaluateVerdict(verdict, reqIds, { tasksHash: tasksHashOf(tarefasMd) });
-      if (!v.ok) {
-        if (v.stale) return { ok: false, failing: ['verdict stale (tarefas.md mudou depois da verificação) — re-verifique: `wendkeep verify --deep` + wk-verify'] };
-        return { ok: false, failing: verdict ? [`verdict incompleto: falta ${v.missing.join(', ')}`] : ['sem verdict — rode `wendkeep verify --deep` + skill wk-verify'] };
+      const hash = tasksHashOf(tarefasMd);
+      if (!verdict) {
+        return { ok: false, failing: [reqIds.length
+          ? 'sem verdict — rode `wendkeep verify --deep` + skill wk-verify'
+          : 'sem verdict — rode `wendkeep verify --deep` (verdict trivial automático)'] };
+      }
+      if (verdict.ok !== true) return { ok: false, failing: ['verdict não-ok — re-verifique a change antes de arquivar'] };
+      if (verdict.tasksHash && verdict.tasksHash !== hash) {
+        return { ok: false, failing: [`verdict stale (tarefas.md mudou depois da verificação) — re-verifique: \`wendkeep verify --deep\`${reqIds.length ? ' + wk-verify' : ''}`] };
+      }
+      if (reqIds.length) {
+        const v = evaluateVerdict(verdict, reqIds, { tasksHash: hash });
+        if (!v.ok) {
+          if (v.stale) return { ok: false, failing: ['verdict stale (tarefas.md mudou depois da verificação) — re-verifique: `wendkeep verify --deep` + wk-verify'] };
+          return { ok: false, failing: [`verdict incompleto: falta ${v.missing.join(', ')}`] };
+        }
       }
       return { ok: true, failing: [] };
     };
-    const r = archiveChange(vaultBase, slug, { dateStr: today(), adrNum: getNextAdrNumber(vaultBase), gate });
+    // Rastro auditável: forced só quando o --force de fato pulou G1 (tarefa aberta); trivial
+    // quando a change não declarou nenhuma prova ([req:]/[sensor:]).
+    let tasks = [];
+    try { tasks = parseTasks(readFileSync(join(vaultBase, getLocale(vaultBase).folders.changes, slug, 'tarefas.md'), 'utf8')); } catch { /* sem tarefas */ }
+    const forced = rest.includes('--force') && tasks.some((t) => !t.done);
+    const trivial = !tasks.some((t) => t.req) && !tasks.some((t) => t.sensor);
+    if (trivial) process.stderr.write('aviso: change trivial (sem [req:]/[sensor:]) — ADR marcado trivial: true\n');
+    const r = archiveChange(vaultBase, slug, { dateStr: today(), adrNum: getNextAdrNumber(vaultBase), gate, adrFlags: { forced, trivial } });
     if (!r.ok) {
       process.stderr.write(`change archive BLOCKED (gate): ${r.failing.join('; ')}\n`);
       process.exit(1);
@@ -206,6 +228,15 @@ export function runChange(argv) {
     process.exit(0);
   }
 
-  process.stderr.write(`wendkeep change: unknown subcommand "${sub}". Known: new, list, show, status, done, undone, diff, archive.\n`);
+  if (sub === 'abandon') {
+    const slug = slugArg() || activeChange(vaultBase);
+    if (!slug) { process.stderr.write('wendkeep change abandon: missing <slug> and no active change\n'); process.exit(2); }
+    const r = abandonChange(vaultBase, slug, { dateStr: today() });
+    if (!r.ok) { process.stderr.write(`wendkeep change abandon: ${r.failing.join('; ')}\n`); process.exit(2); }
+    process.stdout.write(`abandoned: ${r.archivedRel}\n`);
+    process.exit(0);
+  }
+
+  process.stderr.write(`wendkeep change: unknown subcommand "${sub}". Known: new, list, show, status, done, undone, diff, archive, abandon.\n`);
   process.exit(2);
 }

package/src/init.mjs

@@ -9,9 +9,12 @@ import { createInterface } from 'node:readline/promises';
 import {
   VAULT_FOLDERS,
   SESSION_HOOKS,
+  CHANGE_NUDGE_HOOKS,
+  CHANGE_GATE_HOOKS,
   MCP_SERVER_KEY,
   mcpServerEntry,
   hookCommand,
+  hookCommandLocal,
   deriveVaultDirName,
   selectableCompanions,
   resolveCompanions,
@@ -91,27 +94,45 @@ function backup(path) {
 
 // --- merges -----------------------------------------------------------------
 
-export function mergeSettings(existing, { vaultPath, withMcp, force, companions = [], skipMcp = [], dotcontextHookLevel = 'full' }) {
+// Comando preferido para um hook: node-direto quando o projeto tem o pacote local (alta
+// frequência sem cold-start de npx — ver R3 do design 0.31.0); senão o npx portátil.
+export function hookCommandFor(name, projectPath) {
+  try {
+    if (projectPath && existsSync(join(projectPath, 'node_modules', 'wendkeep', 'hooks', `${name}.mjs`))) {
+      return hookCommandLocal(name);
+    }
+  } catch { /* fs indisponível — npx */ }
+  return hookCommand(name);
+}
+
+export function mergeSettings(existing, { vaultPath, withMcp, force, companions = [], skipMcp = [], dotcontextHookLevel = 'full', projectPath = '' }) {
   const s = existing && typeof existing === 'object' ? { ...existing } : {};
   s.hooks = { ...(s.hooks || {}) };
   let added = 0;
-  // wendkeep's own session hooks + any companion-authored hooks. Stable-sort by
-  // `order` (default 0) so higher-order companion hooks (e.g. dotcontext's order 100)
-  // fold AFTER wendkeep's own within each event. A spec may carry its own `command`
-  // (dotcontext dispatch) instead of a wendkeep hook `name`.
-  const allSpecs = [...SESSION_HOOKS, ...companionHookSpecs(companions, { dotcontextHookLevel })].sort(
-    (a, b) => (a.order ?? 0) - (b.order ?? 0),
-  );
+  // wendkeep's own session hooks + the change-lifecycle hooks (0.31.0, default) + any
+  // companion-authored hooks. Stable-sort by `order` (default 0) so higher-order companion
+  // hooks (e.g. dotcontext's order 100) fold AFTER wendkeep's own within each event. A spec
+  // may carry its own `command` (dotcontext dispatch) instead of a wendkeep hook `name`.
+  const allSpecs = [
+    ...SESSION_HOOKS,
+    ...CHANGE_NUDGE_HOOKS,
+    ...CHANGE_GATE_HOOKS,
+    ...companionHookSpecs(companions, { dotcontextHookLevel }),
+  ].sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
   for (const h of allSpecs) {
-    const command = h.command ?? hookCommand(h.name);
+    const command = h.command ?? (h.preferLocal ? hookCommandFor(h.name, projectPath) : hookCommand(h.name));
+    // 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 groups = Array.isArray(s.hooks[h.event]) ? [...s.hooks[h.event]] : [];
-    const owning = groups.find((g) => (g.hooks || []).some((x) => x.command === command));
+    const owning = groups.find((g) => (g.hooks || []).some((x) => candidates.includes(x.command)));
     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) => x.command === command);
+        const hk = owning.hooks.find((x) => candidates.includes(x.command));
+        hk.command = command;
         hk.timeout = h.timeout;
         if (h.statusMessage) hk.statusMessage = h.statusMessage;
         if (h.matcher && (owning.hooks || []).length === 1) owning.matcher = h.matcher;
@@ -477,12 +498,12 @@ export async function runInit(argv) {
   const settingsRead = readJsonSafe(settingsPath);
   if (!settingsRead.ok) {
     // Unparseable existing file — never clobber. Drop a .new for manual merge.
-    const fresh = mergeSettings(null, { vaultPath, withMcp: args.mcp, force: true, companions, skipMcp, dotcontextHookLevel }).settings;
+    const fresh = mergeSettings(null, { vaultPath, withMcp: args.mcp, force: true, companions, skipMcp, dotcontextHookLevel, projectPath }).settings;
     writeJson(`${settingsPath}.new`, fresh);
     log(M.settingsBadJson(settingsPath));
   } else {
     const hadFile = settingsRead.data !== null;
-    const { settings, added } = mergeSettings(settingsRead.data, { vaultPath, withMcp: args.mcp, force: args.force, companions, skipMcp, dotcontextHookLevel });
+    const { settings, added } = mergeSettings(settingsRead.data, { vaultPath, withMcp: args.mcp, force: args.force, companions, skipMcp, dotcontextHookLevel, projectPath });
     if (hadFile) backup(settingsPath);
     writeJson(settingsPath, settings);
     log(M.settings(hadFile ? M.merged : M.created, added, hadFile ? M.bakSaved : ''));

package/src/skills-seed.mjs

@@ -16,6 +16,12 @@ const WORKFLOW = `# Loop a2 — o ciclo de trabalho do wendkeep
 Use ao começar qualquer mudança não-trivial. O loop mantém memória (vault) e prova
 (sensores) juntas, tudo linkado no grafo do Obsidian.
 
+<HARD-GATE>
+NÃO edite arquivos de código antes do passo 2 (Propose / \`wendkeep change new\`).
+Toda tarefa não-trivial passa pelo loop — planejar no chat e sair editando deixa o
+vault cego. Exceção única: mudança trivial (typo, 1 linha).
+</HARD-GATE>
+
 ## Os passos
 
 1. **Explore** — entenda o problema antes de propor. Leia o código/contexto relevante.
@@ -222,6 +228,12 @@ const WORKFLOW_EN = `# The a2 loop — wendkeep's work cycle
 Use it when starting any non-trivial change. The loop keeps memory (vault) and proof
 (sensors) together, wikilinked in the Obsidian graph.
 
+<HARD-GATE>
+Do NOT edit code files before step 2 (Propose / \`wendkeep change new\`).
+Every non-trivial task goes through the loop — planning in chat and editing right away
+leaves the vault blind. Single exception: a trivial change (typo, one line).
+</HARD-GATE>
+
 ## Steps
 
 1. **Explore** — understand the problem before proposing.
@@ -518,21 +530,24 @@ size of the problem>
 <verifiable criteria: for each requirement, the test that fails → passes>
 `;
 
+// As descriptions são o gatilho de ativação: o harness casa a description com o PEDIDO do
+// usuário ("implementa X", "corrige Y"), não com abstrações ("mudança não-trivial"). Gatilhos
+// concretos + instrução imperativa = a skill dispara sozinha (paridade Superpowers).
 const WK_SKILLS_PT = [
-  skill('wk-workflow', 'Use ao começar qualquer mudança não-trivial — orquestra o loop a2 (explore, propose, apply, verify, archive) nos comandos wendkeep.', WORKFLOW),
+  skill('wk-workflow', 'Use SEMPRE que o usuário pedir para implementar, criar, corrigir, refatorar, adicionar ou alterar código — qualquer tarefa de código não-trivial. Invoque ANTES de editar qualquer arquivo: orquestra o loop a2 (wendkeep change new → tarefas → verify → archive) e registra tudo no vault.', WORKFLOW),
   skill('wk-tdd', 'Use ao implementar qualquer comportamento — Red/Green/Refactor com testes que discriminam (derivados do spec, litmus não-raso, adequação).', TDD),
-  skill('wk-debugging', 'Use quando algo falha ou quebra — depuração sistemática por hipótese antes de corrigir.', DEBUGGING),
-  skill('wk-brainstorming', 'Use quando a ideia ainda é vaga — vira design aprovado, com closure gate e tabela out-of-scope, antes de código.', BRAINSTORMING, [{ name: 'design-template.md', content: DESIGN_TEMPLATE_PT }]),
-  skill('wk-planning', 'Use após um design aprovado — decompõe em plano de tarefas TDD bite-sized.', PLANNING, [{ name: 'plan-template.md', content: PLAN_TEMPLATE_PT }]),
+  skill('wk-debugging', 'Use quando algo falha, quebra, dá erro ou regride — depuração sistemática por hipótese antes de corrigir.', DEBUGGING),
+  skill('wk-brainstorming', 'Use quando a ideia ainda é vaga ou o usuário quer discutir/planejar uma feature (inclusive em plan mode) — vira design aprovado, com closure gate e tabela out-of-scope, antes de código.', BRAINSTORMING, [{ name: 'design-template.md', content: DESIGN_TEMPLATE_PT }]),
+  skill('wk-planning', 'Use após um design aprovado ou um plano aceito (inclusive plan mode) — decompõe em plano de tarefas TDD bite-sized e registra na change ativa.', PLANNING, [{ name: 'plan-template.md', content: PLAN_TEMPLATE_PT }]),
   skill('wk-verify', 'Use no verify deep — passe independente read-only (autor≠verificador) que re-deriva a cobertura do spec e grava verdict.json.', VERIFY, [{ name: 'spec-reviewer-prompt.md', content: REVIEWER_PROMPT_PT }, { name: 'verdict-template.json', content: VERDICT_TEMPLATE }]),
 ];
 
 const WK_SKILLS_EN = [
-  skill('wk-workflow', 'Use when starting any non-trivial change — orchestrates the a2 loop (explore, propose, apply, verify, archive) over the wendkeep commands.', WORKFLOW_EN),
+  skill('wk-workflow', 'Use WHENEVER the user asks to implement, create, fix, refactor, add or change code — any non-trivial coding task. Invoke BEFORE editing any file: it orchestrates the a2 loop (wendkeep change new → tasks → verify → archive) and records everything in the vault.', WORKFLOW_EN),
   skill('wk-tdd', 'Use when implementing any behaviour — Red/Green/Refactor with tests that discriminate (spec-derived, non-shallow litmus, adequacy).', TDD_EN),
-  skill('wk-debugging', 'Use when something fails or breaks — systematic hypothesis-driven debugging before fixing.', DEBUGGING_EN),
-  skill('wk-brainstorming', 'Use when the idea is still vague — turns it into an approved design, with a closure gate and out-of-scope table, before code.', BRAINSTORMING_EN, [{ name: 'design-template.md', content: DESIGN_TEMPLATE_EN }]),
-  skill('wk-planning', 'Use after an approved design — decomposes it into a bite-sized TDD task plan.', PLANNING_EN, [{ name: 'plan-template.md', content: PLAN_TEMPLATE_EN }]),
+  skill('wk-debugging', 'Use when something fails, breaks, errors or regresses — systematic hypothesis-driven debugging before fixing.', DEBUGGING_EN),
+  skill('wk-brainstorming', 'Use when the idea is still vague or the user wants to discuss/plan a feature (plan mode included) — turns it into an approved design, with a closure gate and out-of-scope table, before code.', BRAINSTORMING_EN, [{ name: 'design-template.md', content: DESIGN_TEMPLATE_EN }]),
+  skill('wk-planning', 'Use after an approved design or an accepted plan (plan mode included) — decomposes it into a bite-sized TDD task plan recorded in the active change.', PLANNING_EN, [{ name: 'plan-template.md', content: PLAN_TEMPLATE_EN }]),
   skill('wk-verify', 'Use in verify deep — an independent read-only pass (author≠verifier) that re-derives spec coverage and writes verdict.json.', VERIFY_EN, [{ name: 'spec-reviewer-prompt.md', content: REVIEWER_PROMPT_EN }, { name: 'verdict-template.json', content: VERDICT_TEMPLATE }]),
 ];
 
@@ -545,20 +560,22 @@ export const WK_SKILLS = WK_SKILLS_PT;
 // Seed each skill into <brainDir>/skills/<name>/ if absent (non-destructive): SKILL.md plus any
 // bundled template/prompt files. Existing files are never overwritten, so re-seeding an older
 // install just fills in the new template files alongside its SKILL.md.
-export function seedWkSkills(brainDir, localeId = 'pt-BR') {
+// { refresh: true } (sync-defs --reseed) SOBRESCREVE as wk-* com os seeds atuais — é como um
+// vault existente recebe descriptions/HARD-GATE novos (edições manuais nas wk-* são perdidas).
+export function seedWkSkills(brainDir, localeId = 'pt-BR', { refresh = false } = {}) {
   const created = [];
   for (const s of wkSkills(localeId)) {
     const dir = join(brainDir, 'skills', s.name);
     mkdirSync(dir, { recursive: true });
-    const writeIfAbsent = (name, content) => {
+    const write = (name, content) => {
       const f = join(dir, name);
-      if (!existsSync(f)) {
+      if (refresh || !existsSync(f)) {
         writeFileSync(f, content, 'utf8');
         created.push(f);
       }
     };
-    writeIfAbsent('SKILL.md', s.body);
-    for (const file of s.files || []) writeIfAbsent(file.name, file.content);
+    write('SKILL.md', s.body);
+    for (const file of s.files || []) write(file.name, file.content);
   }
   return created;
 }

package/src/sync-defs.mjs

@@ -7,6 +7,8 @@
 // cross-platform robustness.
 import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
+import { seedWkSkills } from './skills-seed.mjs';
+import { getLocale } from '../hooks/locale.mjs';
 
 // Managed AGENTS.md section (0.8.0): the agent-agnostic distribution channel. Codex, Amp,
 // Cursor, Zed et al. read AGENTS.md — one file covers them all. Only the content between
@@ -114,6 +116,12 @@ export function runSyncDefs(argv) {
   }
   const vaultBase = isAbsolute(base) ? base : resolve(process.cwd(), base);
   const projectPath = resolve(project || process.cwd());
+  // --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.
+  if (argv.includes('--reseed')) {
+    const n = seedWkSkills(join(vaultBase, '.brain'), getLocale(vaultBase).id, { refresh: true });
+    process.stdout.write(`wendkeep sync-defs: ${n.length} arquivo(s) de skill re-semeados em .brain/skills\n`);
+  }
   const r = syncDefs(vaultBase, projectPath);
   process.stdout.write(
     `wendkeep sync-defs: ${r.agents.length} agent(s) -> .codex/agents, ${r.skills.length} skill(s) -> .claude/skills\n`,

package/src/taxonomy.mjs

@@ -50,6 +50,11 @@ export const HOOK_FILES = [
   'task-log.mjs',
   'vault-health.mjs',
   'understand-inject.mjs',
+  'change-context.mjs',
+  'change-warn.mjs',
+  'change-guard.mjs',
+  'change-nag.mjs',
+  'plan-capture.mjs',
 ];
 
 // Hook scripts that are safe to invoke directly via `wendkeep hook <name>`.
@@ -68,6 +73,11 @@ export const RUNNABLE_HOOKS = [
   'brain-reindex',
   'vault-health',
   'understand-inject',
+  'change-context',
+  'change-warn',
+  'change-guard',
+  'change-nag',
+  'plan-capture',
 ];
 
 // The MCP server entry wendkeep wires into .mcp.json so the agent can read/write the
@@ -107,6 +117,27 @@ export function hookCommand(name) {
   return `npx wendkeep hook ${name}`;
 }
 
+// Forma node-direta do comando de hook: 1 processo (~100-250ms) em vez dos 3 do npx (cold-start
+// 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 node_modules/wendkeep/hooks/${name}.mjs`;
+}
+
+// Hooks do lifecycle de change (0.31.0) — enforcement do loop a2. Nudges (contexto/aviso/
+// cobrança/captura de plano) e gate (deny/ask no Bash). Separados em dois grupos para
+// preservar a opção futura de gates opt-in; hoje o init wira TODOS por default.
+// preferLocal: alta frequência → invocação node-direta quando houver instalação local.
+export const CHANGE_NUDGE_HOOKS = [
+  { event: 'UserPromptSubmit', matcher: null, name: 'change-context', timeout: 15, order: 10, preferLocal: true, statusMessage: 'wendkeep: change ping' },
+  { event: 'PostToolUse', matcher: 'Edit|Write|MultiEdit', name: 'change-warn', timeout: 10, order: 10, preferLocal: true, statusMessage: 'wendkeep: change warn' },
+  { event: 'PostToolUse', matcher: 'ExitPlanMode', name: 'plan-capture', timeout: 15, order: 10, preferLocal: true, statusMessage: 'wendkeep: capturing approved plan' },
+  { event: 'Stop', matcher: null, name: 'change-nag', timeout: 15, order: 10, preferLocal: true, statusMessage: 'wendkeep: open tasks check' },
+];
+export const CHANGE_GATE_HOOKS = [
+  { event: 'PreToolUse', matcher: 'Bash', name: 'change-guard', timeout: 10, order: 10, preferLocal: true, statusMessage: 'wendkeep: change gate' },
+];
+
 // --- companion plugins / MCP --------------------------------------------------
 // Optional tools wendkeep init can pin alongside the vault. Each is wired through
 // the MOST agent-agnostic mechanism it supports; the Claude Code plugin entry