wendkeep 0.29.2 → 0.31.0

package/CHANGELOG.md

@@ -4,6 +4,95 @@ 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
+- **Decision notes follow the ADR convention: `ADR-<NNNN>-<slug>`.** Every decision note now carries
+  a 4-digit, zero-padded sequential number assigned in the order decisions are made (`ADR-0001`,
+  `ADR-0002`, …) — replacing the old `YYYY-MM-DD-escolha-<slug>` filenames from the interactive and
+  prose captures. The number goes in the filename, in an `adr:` frontmatter field, and as an
+  `# ADR-NNNN — <title>` H1 prefix. The native `wendkeep change archive` ADR and the
+  `createLinkedNotes` heuristic ADR widen from 3 to 4 digits (`ADR-007` → `ADR-0007`) to match.
+- **Decision capture dedups by `content_key`, not by filename.** Because the filename now carries a
+  fresh ADR number it can't dedup, so a decision already recorded in the target folder (same
+  normalized question) is skipped by content — both the AskUserQuestion hook (`captureDecision`) and
+  the agnostic prose capture (`captureProseDecisions`). New `decisionKeyExists` / `padAdr` helpers.
+
+### Added
+- **`wendkeep renumber-decisions`** — retroactive fix for vaults that accumulated the three historical
+  naming eras (`ADR-NNN`, dated `escolha`, hand-written). Renumbers **every** note in 04-Decisões to
+  `ADR-<NNNN>-<slug>` in strict chronological order, renames the files in place, and **rewrites every
+  wikilink to them across the whole vault** (full-path, basename, and `|ADR-006` display aliases).
+  Normalizes each note's `type: decision` / `adr:` / H1. Preview by default (writes nothing); pass
+  `--apply` to commit the renames. Idempotent — a second run on a canonical vault is a no-op.
+  `--vault P` / `--json`. New `hooks/renumber-decisions.mjs` (`planRenumber`, `renumberDecisions`,
+  `slugFromDecisionName`, `decisionSortKey`, `normalizeDecisionContent`, `rewriteLinks`).
+
 ## [0.29.2] — 2026-07-09
 
 ### Fixed

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.
@@ -60,6 +61,9 @@ Usage:
   wendkeep verify [--deep] [--change s]  Run a change's task sensors + record evidence (the gate);
                            --deep assembles the verification package for the wk-verify pass.
   wendkeep dashboard [--force]  (Re)generate the vault's folder-filtered Bases + 00-Dashboard MOC.
+  wendkeep renumber-decisions   Renumber 04-Decisões to ADR-<NNNN>-<slug> in chronological order,
+                           renaming files + rewriting every wikilink. Preview by default; --apply to
+                           write. --vault P · --json.
   wendkeep lesson add "t" "l"   Record a project-local lesson (injected at SessionStart).
   wendkeep validate-memory [path]  Validate .brain/CORE.md against the compaction
                            protocol (cap 25, 3 sections, no secrets/PII). Uses
@@ -67,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.
 `;
@@ -162,6 +168,11 @@ async function main() {
       runDashboard(rest);
       break;
     }
+    case 'renumber-decisions': {
+      const { runRenumberDecisions } = await import('../src/renumber.mjs');
+      runRenumberDecisions(rest);
+      break;
+    }
     case '--version':
     case '-v':
       process.stdout.write(`${version()}\n`);

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 */ }
@@ -265,16 +347,19 @@ export function archiveChange(vaultBase, slug, { gate = gateGreen, dateStr, adrN
   // — not the year root — so all ADRs sit together in the vault's convention.
   const adrDirRel = monthFolderRelFromDateStr(loc.folders.decisions, dateStr, vaultBase);
   ensureDir(join(vaultBase, adrDirRel));
-  const num = String(adrNum).padStart(3, '0');
+  const num = String(adrNum).padStart(4, '0');
   const adrRel = join(adrDirRel, `ADR-${num}-${slug}.md`);
   const capLine = promoted.length
     ? `\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({});
+  }
+}