wendkeep 0.30.0 → 0.32.0

package/CHANGELOG.md

@@ -4,6 +4,115 @@ 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)
+
+- **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).',
-      '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.',
+      '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 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` + 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).',
-    '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.',
+    '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 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.',
+    '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';
@@ -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);
@@ -183,6 +190,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,10 +294,16 @@ 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);
+  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 || [] };
 
@@ -233,16 +319,27 @@ 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 (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 */ }
@@ -261,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);
@@ -271,10 +379,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 +396,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 +404,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({});
+  }
+}