wizz-method 2.18.0 → 2.19.0

package/tools/hooks/wizz-artifact-guard.js

@@ -1,4 +1,4 @@
-// wizz-artifact-guard.js — PostToolUse hook (matcher: Write)
+// wizz-artifact-guard.js — PostToolUse hook (matcher: Write|Edit|MultiEdit)
 //
 // Fonte de verdade: wizz-method/tools/hooks/. Instalar via `npm run sync:global`
 // ou pelo installer (registra em `.claude/settings.json` do projeto).
@@ -12,22 +12,43 @@
 //   2. Arquivo solto na raiz: fora do `layout:` do config. Sugere o destino e
 //      o comando que move atualizando as referências.
 //
+// Edit/MultiEdit só conferem o frontmatter do artefato (lido do disco): o
+// arquivo já existia, então lugar e raiz foram avisados quando ele nasceu.
+//
 // Fail-open: sem `_wizz/`, sem config, payload estranho ou qualquer erro =
 // silêncio e exit 0. Caso comum (arquivo dentro de uma pasta qualquer) custa
 // zero token.
 
+const fs = require('node:fs');
 const path = require('node:path');
 
+// Diagnóstico opt-in (WIZZ_DEBUG=1). Lib ausente numa cópia parcial: ainda avisa em stderr.
+let debug = (hook, phase, err) => {
+  if (process.env.WIZZ_DEBUG !== '1') return;
+  try {
+    process.stderr.write(`[wizz-debug] ${hook} ${phase}: ${(err && err.message) || err}\n`);
+  } catch {
+    // stderr fechado
+  }
+};
+try {
+  ({ debug } = require('./wizz-debug-lib.js'));
+} catch (error) {
+  debug('artifact-guard', 'require wizz-debug-lib', error);
+}
+
 let lib;
 let layoutLib;
 try {
   lib = require('./wizz-feature-lib.js');
   layoutLib = require('./wizz-layout-lib.js');
-} catch {
+} catch (error) {
   lib = null;
+  debug('artifact-guard', 'require wizz-feature-lib/wizz-layout-lib', error);
 }
 
 const HOOK_CMD = '_wizz/hooks';
+const EDIT_TOOLS = new Set(['Edit', 'MultiEdit']);
 
 function isInside(child, parent) {
   const r = path.relative(parent, child);
@@ -40,7 +61,7 @@ function isInside(child, parent) {
  * @param {string} content - conteúdo escrito (pode ser '')
  * @param {ReturnType<typeof lib.resolveFeature>} state
  */
-function artifactWarning(file, content, state) {
+function artifactWarning(file, content, state, { frontmatterOnly = false } = {}) {
   const dirs = lib.artifactDirs(state.root, state.config);
   const base = [dirs.planning, dirs.implementation].find((d) => isInside(file, d));
   if (!base) return '';
@@ -52,7 +73,8 @@ function artifactWarning(file, content, state) {
   const slug = state.slug;
   const msgs = [];
 
-  if (parts.length === 1) {
+  // Edit: o lugar já foi avisado quando o arquivo nasceu; só o frontmatter conta.
+  if (!frontmatterOnly && parts.length === 1) {
     if (lib.PROJECT_WIDE.test(name)) return '';
     if (slug) {
       msgs.push(
@@ -65,7 +87,7 @@ function artifactWarning(file, content, state) {
           `Grave a feature a partir do pedido (node ${HOOK_CMD}/wizz-feature.js definir <slug>) e mova o arquivo para a subpasta dela.`,
       );
     }
-  } else if (slug && parts[0] !== slug) {
+  } else if (!frontmatterOnly && slug && parts[0] !== slug) {
     msgs.push(
       `ARTEFATO EM OUTRA FEATURE: ${relFile} está em "${parts[0]}", mas a ativa é "${slug}". ` +
         `Se o trabalho é de "${slug}", mova; se o assunto mudou, troque a feature (wizz-feature.js definir ${parts[0]}).`,
@@ -107,6 +129,15 @@ function rootWarning(file, state) {
   );
 }
 
+function readOrEmpty(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    debug('artifact-guard', 'readOrEmpty', error);
+    return '';
+  }
+}
+
 /**
  * Decide o aviso a partir do payload do PostToolUse. Pura o bastante para teste.
  * @param {{tool_name?: string, tool_input?: {file_path?: string, content?: string}, cwd?: string}} payload
@@ -114,7 +145,8 @@ function rootWarning(file, state) {
  */
 function buildWarning(payload) {
   if (!lib || !payload || typeof payload !== 'object') return '';
-  if (payload.tool_name && payload.tool_name !== 'Write') return '';
+  const isEdit = EDIT_TOOLS.has(payload.tool_name);
+  if (payload.tool_name && payload.tool_name !== 'Write' && !isEdit) return '';
   const input = payload.tool_input || {};
   if (typeof input.file_path !== 'string' || !input.file_path) return '';
 
@@ -129,6 +161,7 @@ function buildWarning(payload) {
   const first = path.relative(state.root, file).split(path.sep)[0];
   if (first === '_wizz' || first.startsWith('.')) return '';
 
+  if (isEdit) return artifactWarning(file, readOrEmpty(file), state, { frontmatterOnly: true });
   return artifactWarning(file, typeof input.content === 'string' ? input.content : '', state) || rootWarning(file, state);
 }
 
@@ -150,8 +183,9 @@ if (require.main === module) {
           JSON.stringify({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: `📁 Wizz: ${warning}` } }),
         );
       }
-    } catch {
+    } catch (error) {
       // aviso nunca derruba a ferramenta
+      debug('artifact-guard', 'buildWarning', error);
     }
     process.exit(0);
   }

package/tools/hooks/wizz-cerebro-lib.js

@@ -0,0 +1,239 @@
+// wizz-cerebro-lib.js — grava o fechamento de uma feature no Cérebro.
+//
+// Fonte de verdade: wizz-method/tools/hooks/. Não é hook registrado: é a
+// biblioteca do `wizz-feature.js encerrar --cerebro`, copiada junto (installer
+// e sync:global). Tira da memória do modelo o dever de fechamento "bloco
+// Estado + 1 linha na tabela Sessões" (`_shared/cerebro.md`).
+//
+// Regras do protocolo do Cérebro (skill `wizz-cerebro`, comandos-sessao.md):
+//   - vault: `~/Documents/projects/Obsidian Vault/CEREBRO.md`. O `find ~`
+//     do protocolo fica de fora (caro demais para uma CLI); quem usa outro
+//     lugar aponta `WIZZ_CEREBRO_VAULT` ou `cerebro_vault:` no config.
+//   - estado mora em `projetos/<nome>.md`, bloco `## Estado` no topo.
+//   - `Sessões` com teto de 15 linhas; nunca apagar histórico: as antigas
+//     vão para `_index/cerebro-archive.md`, seção `## Sessões antigas —
+//     <projeto>`. Decisão do dono (2026-10-15): sessão antiga já foi feita,
+//     então sai do arquivo que o `/wizz-cerebro ver` lê sempre e fica no arquivo
+//     morto, que só se lê por grep quando precisar. Fora isso, a CLI não toca
+//     nenhum outro arquivo do vault.
+//
+// O bloco Estado é curado à mão; sobrescrever inteiro apagaria o que a CLI
+// não sabe. Então só duas linhas são da CLI: `**Feature `<slug>`:**` (uma
+// por feature) e `**Última sessão:**`. Ambas são substituídas, nunca
+// empilhadas: rodar duas vezes deixa o arquivo idêntico.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const lib = require('./wizz-feature-lib.js');
+
+const SESSIONS_CAP = 15;
+const SUMMARY_MAX = 160;
+const DEFAULT_VAULT = path.join('Documents', 'projects', 'Obsidian Vault');
+const ARCHIVE_FILE = path.join('_index', 'cerebro-archive.md');
+const ARCHIVE_HEADER = [
+  '# Arquivo do Cérebro',
+  '',
+  '> Excedente movido do CEREBRO.md e dos arquivos de projeto. Nada aqui foi apagado, só tirado do índice.',
+  '> Este arquivo é para **grep**, nunca para Read completo.',
+  '',
+];
+
+const hasCerebro = (dir) => {
+  try {
+    return Boolean(dir) && fs.statSync(path.join(dir, 'CEREBRO.md')).isFile();
+  } catch {
+    return false;
+  }
+};
+
+const expandHome = (p) => (p.startsWith('~') ? path.join(os.homedir(), p.slice(1)) : p);
+
+/**
+ * Acha o vault: `WIZZ_CEREBRO_VAULT` > `cerebro_vault` do config > padrão do
+ * protocolo no HOME. Só vale pasta com CEREBRO.md.
+ * @param {Record<string,string>} configValues
+ * @returns {string} caminho do vault ou ''
+ */
+function findVault(configValues = {}) {
+  const candidates = [process.env.WIZZ_CEREBRO_VAULT, configValues.cerebro_vault, path.join(os.homedir(), DEFAULT_VAULT)];
+  for (const c of candidates) {
+    if (typeof c === 'string' && c.trim() && hasCerebro(expandHome(c.trim()))) return expandHome(c.trim());
+  }
+  return '';
+}
+
+/** Arquivo `projetos/<nome>.md` do projeto: --projeto > project_name > pasta. */
+function findProjectFile(vault, root, configValues, projeto) {
+  const names = [projeto, configValues.project_name, path.basename(root)].filter((n) => typeof n === 'string' && n.trim());
+  for (const n of names) {
+    for (const variant of new Set([n.trim(), lib.toSlug(n)])) {
+      const file = path.join(vault, 'projetos', `${variant}.md`);
+      if (variant && fs.existsSync(file)) return file;
+    }
+  }
+  return '';
+}
+
+const oneLine = (s) => s.replaceAll(/\s+/g, ' ').trim();
+const cell = (s) => oneLine(s).replaceAll('|', String.raw`\|`);
+
+/** Primeira linha útil da seção `## Implementação` da spec, ou ''. */
+function implementationSummary(specText) {
+  const content = lib.sectionContent(specText || '', 'Implementa[çc][ãa]o') || '';
+  const first = content.split('\n').find((l) => l.trim()) || '';
+  const clean = oneLine(first.replace(/^[-*]\s+/, ''));
+  return clean.length > SUMMARY_MAX ? `${clean.slice(0, SUMMARY_MAX - 1)}…` : clean;
+}
+
+/** Fim de uma seção `## X` que começa em `start` (próximo `#`/`##` ou EOF). */
+function sectionEnd(lines, start) {
+  let end = start + 1;
+  while (end < lines.length && !/^#{1,2}\s/.test(lines[end])) end++;
+  return end;
+}
+
+const headingIndex = (lines, re) => lines.findIndex((l) => re.test(l.trim()));
+
+/** Onde nasce um bloco Estado novo: abaixo do título e das linhas `>`. */
+function estadoInsertAt(lines) {
+  const title = lines.findIndex((l) => /^#\s/.test(l));
+  if (title === -1) return 0;
+  let i = title + 1;
+  while (i < lines.length && lines[i].startsWith('>')) i++;
+  return i;
+}
+
+/**
+ * Atualiza (ou cria) o bloco `## Estado` com as duas linhas da CLI.
+ * @returns {string[]} linhas novas
+ */
+function upsertEstado(lines, { featureLine, sessionLine, slug }) {
+  const head = headingIndex(lines, /^##\s+Estado\s*$/i);
+  if (head === -1) {
+    const at = estadoInsertAt(lines);
+    const block = ['', '## Estado', featureLine, sessionLine];
+    const rest = lines.slice(at);
+    return [...lines.slice(0, at), ...block, ...(rest[0] === '' ? rest : ['', ...rest])];
+  }
+  const end = sectionEnd(lines, head);
+  const featureKey = `**Feature \`${slug}\`:**`;
+  let body = lines.slice(head + 1, end);
+  const featIdx = body.findIndex((l) => l.includes(featureKey));
+  if (featIdx === -1) body = [...(body[0] === '' ? [''] : []), featureLine, ...body.slice(body[0] === '' ? 1 : 0)];
+  else body = body.map((l, i) => (i === featIdx ? featureLine : l));
+  const sessIdx = body.findIndex((l) => /^\s*-\s+\*\*Última sessão:\*\*/.test(l));
+  if (sessIdx === -1) {
+    let last = body.length;
+    while (last > 0 && body[last - 1].trim() === '') last--;
+    body = [...body.slice(0, last), sessionLine, ...body.slice(last)];
+  } else body = body.map((l, i) => (i === sessIdx ? sessionLine : l));
+  return [...lines.slice(0, head + 1), ...body, ...lines.slice(end)];
+}
+
+/** Separa a tabela de uma seção: {header, rows, tableStart, tableEnd}. */
+function readTable(lines, head) {
+  const end = sectionEnd(lines, head);
+  let start = head + 1;
+  while (start < end && !lines[start].startsWith('|')) start++;
+  if (start >= end || !lines[start + 1] || !/^\|[\s:|-]+\|?\s*$/.test(lines[start + 1])) return null;
+  let stop = start + 2;
+  while (stop < end && lines[stop].startsWith('|')) stop++;
+  return { header: lines.slice(start, start + 2), rows: lines.slice(start + 2, stop), tableStart: start, tableEnd: stop };
+}
+
+const isBlankRow = (row) => row.replaceAll(/[|\s]/g, '') === '';
+
+const escapeRe = (text) => text.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+
+/**
+ * Põe linhas antigas na seção `## Sessões antigas — <projeto>` (formato da skill cerebro) do arquivo
+ * morto (cria a seção no fim se faltar).
+ */
+function archiveRows(lines, overflow, header, projeto) {
+  if (overflow.length === 0) return lines;
+  const title = `## Sessões antigas — ${projeto}`;
+  const head = headingIndex(lines, new RegExp(`^${escapeRe(title)}\\s*$`));
+  if (head === -1) {
+    const base = lines.at(-1) === '' ? lines.slice(0, -1) : lines;
+    return [...base, '', title, ...header, ...overflow, ''];
+  }
+  const table = readTable(lines, head);
+  if (!table) return [...lines.slice(0, head + 1), ...header, ...overflow, ...lines.slice(head + 1)];
+  return [...lines.slice(0, table.tableEnd), ...overflow, ...lines.slice(table.tableEnd)];
+}
+
+/**
+ * Põe (ou substitui) a linha da feature na tabela Sessões, com teto.
+ * Chave de idempotência: mesma data + "`<slug>` encerrada".
+ * @returns {{lines: string[], overflow: string[], header: string[]}} overflow = linhas que saem para o arquivo morto
+ */
+function upsertSessoes(lines, { row, date, slug }) {
+  const head = headingIndex(lines, /^##\s+(Sess(õ|o)es|Sessions)\s*$/i);
+  const header = ['| Data | O que rolou |', '|---|---|'];
+  if (head === -1) {
+    const base = lines.at(-1) === '' ? lines.slice(0, -1) : lines;
+    return { lines: [...base, '', '## Sessões', ...header, row, ''], overflow: [], header };
+  }
+  const table = readTable(lines, head);
+  if (!table) return { lines: [...lines.slice(0, head + 1), ...header, row, ...lines.slice(head + 1)], overflow: [], header };
+  const key = `\`${slug}\` encerrada`;
+  const same = (r) => r.startsWith(`| ${date} |`) && r.includes(key);
+  let rows = table.rows.filter((r) => !isBlankRow(r));
+  rows = rows.some(same) ? rows.map((r) => (same(r) ? row : r)) : [...rows, row];
+  const overflow = rows.length > SESSIONS_CAP ? rows.slice(0, rows.length - SESSIONS_CAP) : [];
+  const kept = rows.slice(overflow.length);
+  const next = [...lines.slice(0, table.tableStart), ...table.header, ...kept, ...lines.slice(table.tableEnd)];
+  return { lines: next, overflow, header: table.header };
+}
+
+/** Grava as linhas que saíram da tabela no arquivo morto do vault. */
+function writeArchive(vault, projeto, overflow, header) {
+  if (overflow.length === 0) return;
+  const file = path.join(vault, ARCHIVE_FILE);
+  const original = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : ARCHIVE_HEADER.join('\n');
+  const next = archiveRows(original.split('\n'), overflow, header, projeto).join('\n');
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  lib.atomicWrite(file, next);
+}
+
+/**
+ * Grava o fechamento no arquivo do projeto no Cérebro. Fail-open: qualquer
+ * falha devolve {gravado: false, motivo} sem lançar.
+ * @param {{root: string, slug: string, status: string, projeto?: string}} input
+ * @returns {{gravado: boolean, arquivo?: string, motivo?: string}}
+ */
+function recordClose({ root, slug, status, projeto }) {
+  try {
+    const { values } = lib.readConfig(root);
+    const vault = findVault(values);
+    if (!vault) return { gravado: false, motivo: 'vault do Cérebro não encontrado (WIZZ_CEREBRO_VAULT)' };
+    const file = findProjectFile(vault, root, values, projeto);
+    if (!file) return { gravado: false, motivo: `sem projetos/<projeto>.md no vault (use --projeto <nome>)` };
+
+    const date = lib.today();
+    const dirs = lib.artifactDirs(root);
+    const spec = path.join(dirs.planning, slug, `spec-${slug}.md`);
+    const specText = fs.existsSync(spec) ? fs.readFileSync(spec, 'utf8') : '';
+    const specRel = path.relative(root, spec);
+    const resumo = implementationSummary(specText);
+    const featureLine = `- **Feature \`${slug}\`:** ${status} em ${date}. Spec: \`${specRel}\`.${resumo ? ` ${resumo}` : ''}`;
+    const sessionLine = `- **Última sessão:** ${date} — feature \`${slug}\` encerrada (${status}).`;
+    const row = `| ${date} | Feature \`${slug}\` encerrada (${status}). ${cell(resumo || `Spec: ${specRel}`)} |`;
+
+    const original = fs.readFileSync(file, 'utf8');
+    let lines = original.split('\n');
+    lines = upsertEstado(lines, { featureLine, sessionLine, slug });
+    const sessoes = upsertSessoes(lines, { row, date, slug });
+    const next = sessoes.lines.join('\n');
+    // Arquivo morto antes do projeto: se a 2ª escrita falhar, a linha fica
+    // duplicada no arquivo morto em vez de sumir.
+    writeArchive(vault, path.basename(file, '.md'), sessoes.overflow, sessoes.header);
+    if (next !== original) lib.atomicWrite(file, next);
+    return { gravado: true, arquivo: file };
+  } catch (error) {
+    return { gravado: false, motivo: error.message };
+  }
+}
+
+module.exports = { findVault, findProjectFile, implementationSummary, upsertEstado, upsertSessoes, recordClose, SESSIONS_CAP };

package/tools/hooks/wizz-close-reminder.js

@@ -0,0 +1,124 @@
+// wizz-close-reminder.js — Stop hook: lembrete de fechamento de feature.
+//
+// Fonte de verdade: wizz-method/tools/hooks/. Instalado em `_wizz/hooks/`
+// (installer) e em `~/.claude/hooks/` (sync:global).
+//
+// No fim de cada turno, se a feature ativa já foi ENTREGUE (spec com status
+// `implementado` ou `no-ar`) e o checklist de fechamento do `wizz-feature.js`
+// ainda tem pendência, mostra 1 aviso ao usuário. Antes isso dependia de o
+// modelo lembrar de rodar `verificar`.
+//
+// Forma da saída: `{"systemMessage": "..."}` no stdout, exit 0. É aviso
+// VISÍVEL ao usuário e não bloqueia: `decision: "block"` forçaria o modelo a
+// continuar o turno, o que vira laço quando a pendência depende do dono.
+//
+// Caminho quente barato: sem subprocesso; sai cedo fora de projeto Wizz, sem
+// feature ativa ou com a feature ainda em andamento (rascunho/aprovado).
+// Silencioso quando não há pendência. Mesmo aviso não repete na mesma sessão
+// (estado por session_id em os.tmpdir(), ou WIZZ_CLOSE_REMINDER_STATE).
+// Fail-open: qualquer erro sai 0 em silêncio.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+// Diagnóstico opt-in (WIZZ_DEBUG=1). Lib ausente numa cópia parcial: ainda avisa em stderr.
+let debug = (hook, phase, err) => {
+  if (process.env.WIZZ_DEBUG !== '1') return;
+  try {
+    process.stderr.write(`[wizz-debug] ${hook} ${phase}: ${(err && err.message) || err}\n`);
+  } catch {
+    // stderr fechado
+  }
+};
+try {
+  ({ debug } = require('./wizz-debug-lib.js'));
+} catch (error) {
+  debug('close-reminder', 'require wizz-debug-lib', error);
+}
+
+const DELIVERED = new Set(['implementado', 'no-ar']);
+const CLI = 'node _wizz/hooks/wizz-feature.js';
+
+/**
+ * Texto do aviso para o projeto em `cwd`, ou '' quando não há o que avisar.
+ * @param {string} cwd
+ * @returns {string}
+ */
+function pendingMessage(cwd) {
+  const lib = require('./wizz-feature-lib.js');
+  const root = lib.findWizzRoot(cwd);
+  if (!root) return '';
+  const state = lib.resolveFeature(root);
+  if (!state.slug) return '';
+  const { artifactPath, checklist } = require('./wizz-feature.js');
+  const spec = artifactPath(root, 'spec', state.slug);
+  if (!fs.existsSync(spec)) return '';
+  const status = lib.parseFrontmatter(fs.readFileSync(spec, 'utf8')).data.status;
+  if (!DELIVERED.has(status)) return '';
+  const { pendentes } = checklist(state, state.slug);
+  const stillActive = status === 'no-ar' && state.fromConfig === state.slug;
+  if (pendentes.length === 0 && !stillActive) return '';
+  const what =
+    pendentes.length > 0
+      ? `pendente: ${pendentes.map((p) => p.item + (p.detalhe ? ` (${p.detalhe})` : '')).join('; ')}`
+      : 'entregue mas ainda ativa';
+  return `⚠️ Fechamento da feature ${state.slug} (${status}) ${what}. Resolva, rode \`${CLI} verificar\` e feche com \`${CLI} encerrar --cerebro\`.`;
+}
+
+function stateFile(sessionId) {
+  const dir = process.env.WIZZ_CLOSE_REMINDER_STATE || path.join(os.tmpdir(), 'wizz-close-reminder');
+  const safe = String(sessionId)
+    .replaceAll(/[^\w-]/g, '')
+    .slice(0, 80);
+  return safe ? path.join(dir, `${safe}.txt`) : '';
+}
+
+/** true se este aviso já saiu nesta sessão; senão grava e devolve false. */
+function alreadyShown(sessionId, message) {
+  const file = sessionId ? stateFile(sessionId) : '';
+  if (!file) return false;
+  const hash = crypto.createHash('sha1').update(message).digest('hex');
+  try {
+    if (fs.readFileSync(file, 'utf8') === hash) return true;
+  } catch {
+    // primeira vez nesta sessão
+  }
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, hash);
+  } catch (error) {
+    // sem dedup: avisa de novo no próximo turno, nunca falha
+    debug('close-reminder', 'alreadyShown write', error);
+  }
+  return false;
+}
+
+function runHook() {
+  const chunks = [];
+  const timer = setTimeout(() => {
+    debug('close-reminder', 'stdin', 'timeout de 3s sem fim de stdin; saindo sem avisar');
+    process.exit(0);
+  }, 3000);
+  process.stdin.on('data', (c) => chunks.push(c));
+  process.stdin.on('end', () => {
+    clearTimeout(timer);
+    try {
+      const payload = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
+      if (payload.stop_hook_active) return;
+      const cwd = payload.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+      const message = pendingMessage(cwd);
+      if (message && !alreadyShown(payload.session_id, message)) {
+        process.stdout.write(`${JSON.stringify({ systemMessage: message })}\n`);
+      }
+    } catch (error) {
+      // fail-open: payload ruim, projeto ilegível, nada disso derruba a sessão
+      debug('close-reminder', 'pendingMessage', error);
+    }
+  });
+}
+
+if (require.main === module) runHook();
+
+module.exports = { pendingMessage };

package/tools/hooks/wizz-debug-lib.js

@@ -0,0 +1,55 @@
+'use strict';
+
+/**
+ * Diagnóstico opt-in dos hooks (fail-open continua valendo).
+ *
+ * Os hooks engolem erro de propósito: nada pode derrubar a sessão. O custo é
+ * que uma cópia parcial em `_wizz/hooks/` faz a feature sumir sem rastro.
+ * Com `WIZZ_DEBUG=1`, cada erro engolido vira UMA linha em stderr e é
+ * anexado a `~/.claude/wizz-debug.log` (`WIZZ_DEBUG_FILE` troca o caminho,
+ * é por onde os testes não encostam no home real).
+ * Sem `WIZZ_DEBUG=1`: zero saída, zero disco.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+function isDebugEnabled() {
+  return process.env.WIZZ_DEBUG === '1';
+}
+
+function debugFilePath() {
+  return process.env.WIZZ_DEBUG_FILE || path.join(os.homedir(), '.claude', 'wizz-debug.log');
+}
+
+/** Formata a linha: `[wizz-debug] <hook> <fase>: <mensagem>` (sem quebra interna). */
+function formatLine(hook, phase, err) {
+  const message = String((err && err.message) || err || 'erro desconhecido').replaceAll(/\s*\n\s*/g, ' ');
+  return `[wizz-debug] ${hook} ${phase}: ${message}`;
+}
+
+/**
+ * Registra um erro engolido. Nunca lança, nunca altera o exit code.
+ * @param {string} hook - nome do hook (ex.: 'session-rules')
+ * @param {string} phase - onde falhou (ex.: 'require wizz-feature-lib')
+ * @param {unknown} err
+ */
+function debug(hook, phase, err) {
+  if (!isDebugEnabled()) return;
+  const line = formatLine(hook, phase, err);
+  try {
+    process.stderr.write(`${line}\n`);
+  } catch {
+    // stderr fechado: o log em disco ainda tenta
+  }
+  try {
+    const file = debugFilePath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, `${new Date().toISOString()} ${line}\n`);
+  } catch {
+    // diagnóstico nunca derruba o hook
+  }
+}
+
+module.exports = { debug, isDebugEnabled, debugFilePath, formatLine };

package/tools/hooks/wizz-decision-trace.js

@@ -56,6 +56,21 @@
 // erro do hook: qualquer falha aqui (arquivo de offsets corrompido, disco
 // cheio, permissão) nunca derruba o hook — fail-silent, volta a reler tudo.
 
+// Diagnóstico opt-in (WIZZ_DEBUG=1). Lib ausente numa cópia parcial: ainda avisa em stderr.
+let debug = (hook, phase, err) => {
+  if (process.env.WIZZ_DEBUG !== '1') return;
+  try {
+    process.stderr.write(`[wizz-debug] ${hook} ${phase}: ${(err && err.message) || err}\n`);
+  } catch {
+    // stderr fechado
+  }
+};
+try {
+  ({ debug } = require('./wizz-debug-lib.js'));
+} catch (error) {
+  debug('decision-trace', 'require wizz-debug-lib', error);
+}
+
 const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
@@ -294,8 +309,9 @@ function extractDecision(text) {
 function appendDecision(entry) {
   try {
     fs.appendFileSync(getTraceFile(), JSON.stringify(entry) + '\n');
-  } catch {
+  } catch (error) {
     // trace nunca pode derrubar o hook
+    debug('decision-trace', 'appendDecision', error);
   }
 }
 
@@ -358,8 +374,9 @@ function runHook() {
       });
 
       process.exit(0);
-    } catch {
+    } catch (error) {
       // Falha em silêncio em qualquer etapa — nunca bloqueia a sessão.
+      debug('decision-trace', 'runHook', error);
       process.exit(0);
     }
   });

package/tools/hooks/wizz-feature.js

@@ -13,7 +13,9 @@
 //   status <status>          rascunho|aprovado|implementado|no-ar na spec
 //   verificar                checklist de fechamento (exit 1 se houver pendência)
 //   encerrar                 status final na spec, limpa/troca active_feature
-//                            (recusa com pendência do checklist, salvo --forcar)
+//                            (recusa com pendência do checklist, salvo --forcar);
+//                            com --cerebro grava Estado + linha de Sessões no
+//                            projetos/<projeto>.md do Cérebro (--projeto <nome>)
 //   listar                   features com pasta e o status de cada spec
 //
 // Opções: --json (saída para máquina), --cwd <dir>, --feature <slug>.
@@ -22,6 +24,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const lib = require('./wizz-feature-lib.js');
+const cerebro = require('./wizz-cerebro-lib.js');
 
 const ALIASES = {
   resolve: 'resolver',
@@ -286,7 +289,7 @@ function checklist(state, slug, { statusOverride } = {}) {
   }
   const pendentes = items.filter((i) => !i.ok);
   const confirmar = [
-    'Cérebro: bloco Estado do projeto atualizado + 1 linha na tabela Sessões',
+    'Cérebro: bloco Estado do projeto atualizado + 1 linha na tabela Sessões (`encerrar --cerebro` grava sozinho)',
     'Auto-memória: só armadilha reproduzível ou preferência do dono (estado e decisão vão no Cérebro)',
   ];
   return { items, pendentes, confirmar };
@@ -305,6 +308,12 @@ function cmdVerificar(state, opts) {
   };
 }
 
+/** `--cerebro`: grava no vault; fail-open, nunca desfaz o encerramento. */
+function cerebroClose(state, slug, status, opts) {
+  const projeto = typeof opts.projeto === 'string' ? opts.projeto : '';
+  return cerebro.recordClose({ root: state.root, slug, status, projeto });
+}
+
 function cmdEncerrar(state, opts) {
   const slug = requireFeature(state, opts);
   if (!slug) return { ok: false, code: 2, line: 'Nenhuma feature ativa para encerrar.' };
@@ -330,9 +339,16 @@ function cmdEncerrar(state, opts) {
   const parts = [`Feature ${slug} encerrada (${status}) em ${lib.today()}. Spec: ${rel(state.root, file)}.`];
   parts.push(next ? `Feature ativa agora: ${next}.` : 'Nenhuma feature ativa agora.');
   if (state.fromBranch === slug) parts.push(`O branch ${state.git.branch} ainda aponta para ${slug}: volte ao tronco ou troque de branch.`);
-  parts.push(`Registre no Cérebro: Estado do projeto + linha na tabela Sessões (${slug}: ${status} em ${lib.today()}).`);
+  const memo = opts.cerebro ? cerebroClose(state, slug, status, opts) : null;
+  if (memo && memo.gravado) parts.push(`Cérebro atualizado: ${memo.arquivo} (Estado + linha em Sessões).`);
+  else {
+    if (memo) parts.push(`Cérebro não gravado (${memo.motivo}).`);
+    parts.push(`Registre no Cérebro: Estado do projeto + linha na tabela Sessões (${slug}: ${status} em ${lib.today()}).`);
+  }
   if (pend.length > 0) parts.push(`Pendências: ${pend.map((p) => p.item).join('; ')}.`);
-  return { ok: true, data: { feature: slug, status, proxima: next, pendencias: pend.map((p) => p.item) }, line: parts.join(' ') };
+  const data = { feature: slug, status, proxima: next, pendencias: pend.map((p) => p.item) };
+  if (memo) data.cerebro = memo;
+  return { ok: true, data, line: parts.join(' ') };
 }
 
 function cmdListar(state) {