wizz-method 2.0.0 → 2.1.1

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

@@ -0,0 +1,389 @@
+// wizz-decision-trace.js — Stop event hook (v1)
+//
+// Fonte de verdade: wizz-method/tools/hooks/. Instalar em ~/.claude/hooks via
+// `npm run sync:global` (nunca editar a cópia global direto — ela é
+// substituída pelo sync).
+//
+// Fecha a lacuna "o trace grava o que foi INJETADO, não o que foi OBEDECIDO":
+// tools/hooks/wizz-router-enforce.js (UserPromptSubmit) já grava, opt-in via
+// WIZZ_TRACE=1, qual contexto de roteamento foi injetado no prompt. Mas
+// injetar não é obedecer — o agente pode ignorar a dica. Para medir a
+// decisão de fato tomada, todo agente wizz emite, no fecho de um pedido
+// roteado (ver src/modules/wizz/_shared/encerramento.md), 1 linha marcador:
+//
+//   🧭 {"rota":"agent:designer","sel":["wizz-canvas-design"],"desc":[["hyperframes","motivo"]],"gate":"ok","repetiria":true}
+//
+// Este hook roda no evento Stop (fim da resposta do assistant). Ele lê o
+// transcript apontado por `transcript_path` no payload do hook, pega a
+// ÚLTIMA mensagem do assistant, extrai a última ocorrência do marcador 🧭 e
+// appenda uma linha `{"type":"decision",...}` no MESMO arquivo usado pelo
+// enforce (~/.claude/wizz-trace.jsonl, honrando WIZZ_TRACE_FILE) — os dois
+// hooks compartilham o mesmo JSONL, distinguível pelo campo `type`
+// ("decision" aqui; as linhas do enforce não têm esse campo).
+//
+// Opt-in: só faz algo com WIZZ_TRACE=1 (mesma convenção do enforce); senão
+// sai 0 sem tocar em disco nem ler o transcript. Nem todo pedido é roteado
+// (marcador ausente é normal, não é erro) e o marcador é telemetria: falha
+// em QUALQUER etapa (payload inválido, transcript ilegível, JSON do marcador
+// quebrado) sai 0 em silêncio — este hook nunca pode bloquear ou derrubar a
+// sessão.
+//
+// P1 da auditoria 360° (medir aderência à escada de modelos): no MESMO passe
+// de leitura do transcript, quando há marcador de decisão no turno, também
+// varre o turno atual em busca de invocação de subagente wizz-exec-*
+// (Task/Agent com subagent_type contendo "wizz-exec") e appenda uma segunda
+// linha `{"type":"ladder",...}` no mesmo JSONL — mesmas garantias de
+// opt-in/fail-silent/custo-zero. Só medição, nenhum enforcement novo.
+//
+// RT-H4 da auditoria 2026-09-11 (item 12, Fase 2): em sessão longa, reler o
+// transcript inteiro a cada `Stop` é O(n) por turno (custo cresce quadrático
+// ao longo da sessão). Correção: um offset em bytes por transcript, salvo em
+// `wizz-trace.offsets.json` ao lado do trace file (mesmo diretório de
+// `getTraceFile()`, então honra `WIZZ_TRACE_FILE`). A cada Stop, lê só os
+// bytes novos desde o offset salvo (ver `readTranscriptDelta`):
+//   - transcript encolheu (offset > tamanho atual — sessão nova reusando o
+//     mesmo path, ou arquivo truncado) → recomeça do zero;
+//   - última linha do delta sem `\n` no final (escrita em andamento, JSON
+//     cortado no meio) → não avança o offset além do último `\n` completo;
+//     tenta de novo no próximo Stop;
+//   - efeito colateral bom: como só processa bytes NOVOS, um turno sem
+//     conteúdo novo desde o último Stop não pode reemitir o marcador de um
+//     turno já registrado — dedup vem de graça do próprio offset, sem
+//     precisar de um mecanismo separado.
+// O arquivo de offsets é podado a cada escrita (entradas cujo transcript já
+// não existe mais são removidas; teto de 50 entradas, mais recentes
+// primeiro) e escrito de forma atômica (tmp + rename). Mesma política de
+// erro do hook: qualquer falha aqui (arquivo de offsets corrompido, disco
+// cheio, permissão) nunca derruba o hook — fail-silent, volta a reler tudo.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+// Captura, na mesma linha do marcador, do `{` até o último `}` daquela
+// linha. Suficiente porque o marcador é sempre um objeto JSON plano — `desc`
+// usa array de arrays (`[...]`), nunca objetos aninhados — então o último
+// `}` da linha é sempre o fechamento do próprio marcador.
+const MARKER_LINE_RE = /🧭\s*(\{[\s\S]*\})\s*$/;
+
+// Detecta invocação de subagente da escada de modelos: tool_use de
+// Task/Agent cujo subagent_type (ou campo equivalente) contém "wizz-exec"
+// (case-insensitive — cobre wizz-exec-haiku/sonnet/opus/review).
+const EXEC_NAME_RE = /wizz-exec/i;
+
+function isTraceEnabled() {
+  return process.env.WIZZ_TRACE === '1';
+}
+
+function getTraceFile() {
+  return process.env.WIZZ_TRACE_FILE || path.join(os.homedir(), '.claude', 'wizz-trace.jsonl');
+}
+
+// Concatena todos os blocos `type: "text"` do conteúdo de uma mensagem de
+// assistant (o array `content` mistura text/tool_use/thinking/etc. — só nos
+// interessa texto).
+function extractAssistantText(entry) {
+  const content = entry && entry.message && entry.message.content;
+  if (!Array.isArray(content)) return '';
+  return content
+    .filter((block) => block && block.type === 'text' && typeof block.text === 'string')
+    .map((block) => block.text)
+    .join('\n');
+}
+
+// Lê o transcript (JSONL, 1 mensagem por linha) e devolve o array de
+// entradas já parseadas. Linhas corrompidas são ignoradas (fail-open). Passe
+// único de leitura do disco — tanto o marcador de decisão quanto a detecção
+// de execs da escada de modelos partem deste mesmo array em memória.
+function readTranscriptEntries(transcriptPath) {
+  const raw = fs.readFileSync(transcriptPath, 'utf8');
+  return parseJsonlText(raw);
+}
+
+// Parseia texto JSONL (1 objeto por linha) em array de entradas. Linhas
+// corrompidas/vazias são ignoradas (fail-open) — usado tanto pela leitura
+// completa (`readTranscriptEntries`, mantida por compat/testes) quanto pela
+// leitura incremental (`readTranscriptDelta`).
+function parseJsonlText(text) {
+  const entries = [];
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      entries.push(JSON.parse(trimmed));
+    } catch {
+      continue; // linha corrompida — ignora, não derruba a leitura
+    }
+  }
+  return entries;
+}
+
+const MAX_OFFSET_ENTRIES = 50;
+
+// Arquivo de offsets fica no MESMO diretório do trace file — assim honra
+// WIZZ_TRACE_FILE automaticamente sem precisar de uma env var própria.
+function getOffsetsFile() {
+  return path.join(path.dirname(getTraceFile()), 'wizz-trace.offsets.json');
+}
+
+// Lê o arquivo de offsets. Fail-open: ausente, JSON inválido, ou formato
+// inesperado → lista vazia (equivalente a "nunca lemos nenhum transcript
+// antes", reprocessa tudo do zero pros transcripts em questão).
+function loadOffsets() {
+  try {
+    const raw = fs.readFileSync(getOffsetsFile(), 'utf8');
+    const data = JSON.parse(raw);
+    if (!data || !Array.isArray(data.entries)) return [];
+    return data.entries.filter((e) => e && typeof e.path === 'string' && Number.isFinite(e.offset) && e.offset >= 0);
+  } catch {
+    return [];
+  }
+}
+
+// Persiste a lista de offsets de forma atômica (tmp + rename no mesmo
+// diretório). Antes de escrever: poda entradas órfãs (transcript que já não
+// existe mais em disco) e limita ao teto de MAX_OFFSET_ENTRIES (a lista já
+// chega ordenada mais-recente-primeiro por `upsertOffset`). Fail-silent —
+// nunca lança; se a escrita falhar, o próximo Stop simplesmente relê tudo de
+// novo pros transcripts afetados (mesma política de erro do resto do hook).
+function saveOffsets(entries) {
+  try {
+    const alive = entries.filter((e) => {
+      try {
+        return fs.existsSync(e.path);
+      } catch {
+        return false;
+      }
+    });
+    const capped = alive.slice(0, MAX_OFFSET_ENTRIES);
+    const offsetsFile = getOffsetsFile();
+    const dir = path.dirname(offsetsFile);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmpFile = path.join(dir, `.wizz-trace.offsets.${process.pid}.${Date.now()}.tmp`);
+    fs.writeFileSync(tmpFile, JSON.stringify({ entries: capped }));
+    fs.renameSync(tmpFile, offsetsFile);
+  } catch {
+    // arquivo de offsets nunca pode derrubar o hook
+  }
+}
+
+// Devolve uma nova lista com a entrada de `transcriptPath` movida (ou
+// inserida) na FRENTE — mantém a lista ordenada mais-recente-primeiro, que é
+// a ordem que `saveOffsets` usa pra decidir quem poda quando passa do teto.
+function upsertOffset(entries, transcriptPath, offset) {
+  const key = path.resolve(transcriptPath);
+  const rest = entries.filter((e) => path.resolve(e.path) !== key);
+  return [{ path: key, offset, ts: new Date().toISOString() }, ...rest];
+}
+
+function getStoredOffset(entries, transcriptPath) {
+  const key = path.resolve(transcriptPath);
+  const found = entries.find((e) => path.resolve(e.path) === key);
+  return found ? found.offset : 0;
+}
+
+// Lê só os bytes NOVOS do transcript desde `storedOffset`. Devolve
+// `{ entries, newOffset }`:
+//   - `entries`: já parseadas (linhas corrompidas ignoradas, fail-open),
+//     só as do delta lido nesta chamada;
+//   - `newOffset`: até onde dá pra avançar com segurança.
+//
+// Duas garantias de robustez (RT-H4):
+//   1. Transcript encolheu (storedOffset > tamanho atual — sessão nova
+//      reusando o mesmo path, ou arquivo truncado) → relê do zero.
+//   2. Delta termina no meio de uma linha (sem `\n` final — escrita em
+//      andamento) → não avança o offset além do último `\n` completo; a
+//      leitura seguinte relê esse trecho junto com o resto que faltava.
+//      Corte feito nos BYTES crus (0x0A), não na string decodificada: `\n`
+//      nunca aparece como parte de uma sequência UTF-8 multibyte (bytes de
+//      continuação/liderança nunca valem 0x0A), então cortar ali nunca
+//      quebra um caractere multibyte ao meio.
+function readTranscriptDelta(transcriptPath, storedOffset) {
+  const size = fs.statSync(transcriptPath).size;
+  const startOffset = storedOffset > size ? 0 : storedOffset;
+
+  if (startOffset >= size) {
+    return { entries: [], newOffset: startOffset };
+  }
+
+  const length = size - startOffset;
+  const buffer = Buffer.alloc(length);
+  const fd = fs.openSync(transcriptPath, 'r');
+  let bytesRead = 0;
+  try {
+    bytesRead = fs.readSync(fd, buffer, 0, length, startOffset);
+  } finally {
+    fs.closeSync(fd);
+  }
+
+  const lastNewline = buffer.lastIndexOf(0x0a, bytesRead - 1);
+  if (lastNewline === -1) {
+    // Nenhuma linha completa neste delta — não avança, tenta de novo depois.
+    return { entries: [], newOffset: startOffset };
+  }
+
+  const usable = buffer.subarray(0, lastNewline + 1);
+  const newOffset = startOffset + usable.length;
+  const entries = parseJsonlText(usable.toString('utf8'));
+  return { entries, newOffset };
+}
+
+// Devolve o texto da ÚLTIMA mensagem de assistant entre as entradas dadas;
+// '' se não houver nenhuma.
+function lastAssistantText(entries) {
+  let lastText = '';
+  for (const entry of entries) {
+    if (entry && entry.type === 'assistant') {
+      const text = extractAssistantText(entry);
+      if (text) lastText = text;
+    }
+  }
+  return lastText;
+}
+
+// Varre só o TURNO ATUAL (entradas depois da última mensagem de `user`) em
+// busca de tool_use de Task/Agent cujo subagent_type contenha "wizz-exec".
+// Execs de turnos anteriores não contam — o objetivo é medir a escada de
+// modelos usada NESTE pedido, não o histórico acumulado da sessão.
+function extractExecInvocations(entries) {
+  let lastUserIndex = -1;
+  for (const [i, entry] of entries.entries()) {
+    if (entry && entry.type === 'user') lastUserIndex = i;
+  }
+  const currentTurn = entries.slice(lastUserIndex + 1);
+
+  const execs = [];
+  for (const entry of currentTurn) {
+    if (!entry || entry.type !== 'assistant') continue;
+    const content = entry.message && entry.message.content;
+    if (!Array.isArray(content)) continue;
+    for (const block of content) {
+      if (!block || block.type !== 'tool_use') continue;
+      if (block.name !== 'Task' && block.name !== 'Agent') continue;
+      const input = block.input || {};
+      const candidate = input.subagent_type || input.subagentType || input.agent || block.name;
+      if (typeof candidate === 'string' && EXEC_NAME_RE.test(candidate)) {
+        execs.push(candidate);
+      }
+    }
+  }
+  return execs;
+}
+
+// Extrai a última ocorrência do marcador 🧭 {...} num texto e devolve o
+// objeto já parseado, ou `null` se o marcador estiver ausente ou o JSON for
+// inválido.
+function extractDecision(text) {
+  if (!text) return null;
+  const lines = text.split('\n');
+  let lastRaw = null;
+  for (const line of lines) {
+    const match = MARKER_LINE_RE.exec(line);
+    if (match) lastRaw = match[1];
+  }
+  if (!lastRaw) return null;
+  try {
+    return JSON.parse(lastRaw);
+  } catch {
+    return null;
+  }
+}
+
+// Appenda 1 linha JSON no trace file. Fail-silent — nunca lança.
+function appendDecision(entry) {
+  try {
+    fs.appendFileSync(getTraceFile(), JSON.stringify(entry) + '\n');
+  } catch {
+    // trace nunca pode derrubar o hook
+  }
+}
+
+function runHook() {
+  let input = '';
+  const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => (input += chunk));
+  process.stdin.on('end', () => {
+    clearTimeout(stdinTimeout);
+    try {
+      // Custo zero quando desligado: nem chega a tocar no payload/transcript.
+      if (!isTraceEnabled()) {
+        process.exit(0);
+        return;
+      }
+
+      const payload = JSON.parse(input);
+      const transcriptPath = payload.transcript_path;
+      if (!transcriptPath || !fs.existsSync(transcriptPath)) {
+        process.exit(0);
+        return;
+      }
+
+      // RT-H4: lê só o delta desde o offset salvo (não o transcript inteiro)
+      // e já persiste o offset avançado antes de decidir se há marcador —
+      // um turno sem marcador (pedido não roteado, caso comum) não pode
+      // forçar releitura do mesmo trecho no próximo Stop.
+      const offsetsBefore = loadOffsets();
+      const storedOffset = getStoredOffset(offsetsBefore, transcriptPath);
+      const { entries, newOffset } = readTranscriptDelta(transcriptPath, storedOffset);
+      saveOffsets(upsertOffset(offsetsBefore, transcriptPath, newOffset));
+
+      const lastText = lastAssistantText(entries);
+      const decision = extractDecision(lastText);
+      if (!decision) {
+        process.exit(0); // nem todo pedido é roteado — ausência é normal
+        return;
+      }
+
+      const ts = new Date().toISOString();
+      const sessionId = payload.session_id || null;
+
+      appendDecision({
+        ts,
+        type: 'decision',
+        session: sessionId,
+        decision,
+      });
+
+      // Mesmo turno, mesmo passe de leitura: registra a escada de modelos
+      // (quais wizz-exec-* foram invocados neste pedido roteado, se algum).
+      const execs = extractExecInvocations(entries);
+      appendDecision({
+        ts,
+        type: 'ladder',
+        sessionId,
+        execs,
+        rota: decision.rota || null,
+      });
+
+      process.exit(0);
+    } catch {
+      // Falha em silêncio em qualquer etapa — nunca bloqueia a sessão.
+      process.exit(0);
+    }
+  });
+}
+
+if (require.main === module) {
+  runHook();
+} else {
+  module.exports = {
+    isTraceEnabled,
+    getTraceFile,
+    extractAssistantText,
+    readTranscriptEntries,
+    lastAssistantText,
+    extractDecision,
+    extractExecInvocations,
+    appendDecision,
+    runHook,
+    // RT-H4: offset persistido (item 12, Fase 2)
+    getOffsetsFile,
+    loadOffsets,
+    saveOffsets,
+    upsertOffset,
+    getStoredOffset,
+    readTranscriptDelta,
+    MAX_OFFSET_ENTRIES,
+  };
+}

package/tools/hooks/wizz-router-enforce.js

@@ -0,0 +1,258 @@
+// wizz-router-enforce.js — UserPromptSubmit hook (v2)
+//
+// Fonte de verdade: wizz-method/tools/hooks/. Instalar em ~/.claude/hooks via
+// `npm run sync:global` (nunca editar a cópia global direto — ela é substituída).
+//
+// v2 (2026-07): detecta projeto Wizz (_wizz/ no cwd ou ancestrais) e injeta uma
+// dica CURTA de delegação direta (maestro/agente da área) em vez do mandato
+// completo do router. Fora de projeto Wizz mantém o router, também em versão
+// curta. Injeção caiu de ~250 para ~50-70 tokens por prompt.
+//
+// Advisory-only: nunca bloqueia o prompt; falha em silêncio.
+//
+// Observabilidade (opt-in, custo zero quando desligado):
+// - WIZZ_TRACE=1 grava uma linha JSON por decisão em ~/.claude/wizz-trace.jsonl
+//   (override: WIZZ_TRACE_FILE). Trace é sempre fail-silent — nunca derruba o hook.
+// - Fallback de roteamento (tabela flat ausente no global, install de projeto
+//   Wizz incompleto) emite 1 warning em stderr, independente do trace estar
+//   ligado. Custo: 1 fs.existsSync por prompt não-trivial.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+// "Abridores" triviais: saudação, confirmação/reação curta, pergunta pura de
+// status, frase de suporte pessoal. Casam só o INÍCIO do prompt — o que vem
+// depois é avaliado à parte via MAX_LEFTOVER_WORDS logo abaixo. Isso corrige o
+// achado RT-H1 da auditoria de 2026-09-11 (_audit/2026-09-11-anexos/03-runtime.md):
+// antes, essas regexes casavam só o prefixo e qualquer coisa depois (mesmo um
+// pedido real e substancial, ex. "sim, e também refatora o módulo de auth")
+// era engolida como trivial junto.
+// Nota: "tá"/"está" terminam em vogal acentuada, e o \w do JS (sem flag /u)
+// não considera acento como caractere de palavra — um \b logo depois falha
+// (nenhum dos dois lados conta como "palavra"). Por isso a entrada de status
+// abaixo não fecha com \b (a checagem de sobra via MAX_LEFTOVER_WORDS já
+// garante que não vira prefixo solto de uma palavra maior).
+const OPENER_PATTERNS = [
+  // Conversa pura / saudações / reação sem pedido
+  /^(oi|ol[aá]|hey|hi|hello|tudo bem|bom dia|boa tarde|boa noite|obrigad[oa]|valeu|vlw|ok|okay|certo|perfeito|show|massa|legal|beleza)\b/i,
+  // Resposta a pergunta do próprio router — evita re-injetar no follow-up
+  /^(sim|n[aã]o|todas|nenhuma|cancela|dispara?\s+(todas|ambas|essas|todas\s+as\s+skills)|pode|vai|continua|[12]|y|n)\b/i,
+  // Perguntas puras de status / o que foi feito
+  /^(o que foi feito|qual o status|me conta|como (t[aá]|est[aá]|ficou|ficaram)|me mostra|explica)/i,
+  // Frase de suporte/estado pessoal ("esqueci a senha") — informacional, não é tarefa
+  /^esqueci\b/i,
+];
+
+// Marcadores de edição pontual/trivial em QUALQUER posição do prompt — não são
+// "resposta curta", são um tipo de pedido que já é trivial por conteúdo
+// (typo, rename, linha específica), então continuam casando como substring.
+const MARKER_PATTERNS = [
+  /\btypo\b/i,
+  /\bcorrige?\s+(esse|este|o|a)?\s*typo\b/i,
+  /\brename\s+(a\s+)?(vari[aá]vel|fun[cç][aã]o|arquivo|classe|m[eé]todo)\b/i,
+  /\brenomei[ao]\s+(a\s+)?(vari[aá]vel|fun[cç][aã]o|arquivo|classe|m[eé]todo)\b/i,
+  // Rename no formato "rebatiza/renomeia X para Y" (objeto é nome próprio, não termo técnico)
+  /\b(rename|renomeia|renomear|renomeou|rebatiza|rebatizar|rebatizou)\b.*\bpara\b/i,
+  // Edição pontual apontando linha específica ("troca X por Y na linha 42")
+  /\bna linha \d+\b/i,
+];
+
+// Depois de casar um abridor, quantas palavras de sobra ainda contam como a
+// mesma reação curta ("tudo bem?", "o resultado", "pode") em vez de um pedido
+// novo emendado ("e também refatora o módulo de auth", 7 palavras de sobra).
+const MAX_LEFTOVER_WORDS = 2;
+
+// Remove pontuação/conectivo solto nas bordas da sobra antes de contar
+// palavras — "ok, pode" deixa a sobra ", pode" -> "pode".
+function normalizeLeftover(text) {
+  return text.replace(/^[\s,;:.!-]+/, '').replace(/[\s.,!?;:…-]+$/u, '');
+}
+
+function countWords(text) {
+  const trimmed = text.trim();
+  return trimmed ? trimmed.split(/\s+/).length : 0;
+}
+
+function isTrivial(prompt) {
+  const trimmed = String(prompt || '').trim();
+  if (!trimmed) return true;
+
+  // Slash command — já roteado explicitamente
+  if (trimmed.startsWith('/')) return true;
+
+  // Pergunta de 1 palavra só ("link?", "cadê?") — informacional, sem pedido de trabalho
+  if (/^\S+\?$/.test(trimmed)) return true;
+
+  for (const pattern of MARKER_PATTERNS) {
+    if (pattern.test(trimmed)) return true;
+  }
+
+  for (const pattern of OPENER_PATTERNS) {
+    const match = pattern.exec(trimmed);
+    if (!match) continue;
+    const leftover = normalizeLeftover(trimmed.slice(match[0].length));
+    if (countWords(leftover) <= MAX_LEFTOVER_WORDS) return true;
+  }
+
+  // Sem heurística de tamanho para o prompt inteiro: um prompt curto e
+  // ambíguo que NÃO começa com abridor (ex.: "e o funil?", "melhora isso")
+  // não é trivial por padrão. Custo de injetar contexto à toa é ~50-70
+  // tokens; custo de deixar um pedido real escapar do roteamento é alto (ver
+  // bug de 2026-08-19 e o RT-H1 acima). Só os abridores + sobra curta, ou os
+  // marcadores de conteúdo, marcam trivial.
+  return false;
+}
+
+// Sobe no máximo 8 níveis procurando _wizz/ (projeto Wizz instalado).
+function findWizzRoot(startDir) {
+  let dir = startDir;
+  for (let i = 0; i < 8 && dir; i++) {
+    try {
+      if (fs.existsSync(path.join(dir, '_wizz'))) return dir;
+    } catch {
+      return null;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+function buildContext(isWizzProject) {
+  if (isWizzProject) {
+    return (
+      '🎛️ Projeto Wizz: NÃO invoque wizz-router. 2+ áreas → sempre Skill `wizz-maestro`. ' +
+      '1 área: 2+ fatores (multi-passo, planejar, artefato memorável) → `wizz-maestro`; ' +
+      'senão → Skill do agente da área (ex: wizz-designer, wizz-quick-dev). ' +
+      'Personas são skills, não subagent_type; Agent usa tipos disponíveis wizz-exec-*. Trivial → direto.'
+    );
+  }
+  return (
+    '🎛️ Pedido não-trivial: invoque a Skill `wizz-router` antes de agir para ' +
+    'mapear skills/MCPs (liste candidatas via AskUserQuestion e confirme). ' +
+    'Exceção: edição trivial de 1 linha e conversa pura.'
+  );
+}
+
+function isTraceEnabled() {
+  return process.env.WIZZ_TRACE === '1';
+}
+
+function getTraceFile() {
+  return process.env.WIZZ_TRACE_FILE || path.join(os.homedir(), '.claude', 'wizz-trace.jsonl');
+}
+
+// Grava 1 linha JSON por decisão quando WIZZ_TRACE=1. Append-only,
+// fail-silent, e não faz nada (nem chega a serializar) quando desligado —
+// custo zero no caminho comum.
+function traceLine(entry) {
+  if (!isTraceEnabled()) return;
+  try {
+    fs.appendFileSync(getTraceFile(), JSON.stringify(entry) + '\n');
+  } catch {
+    // trace nunca pode derrubar o hook
+  }
+}
+
+function getGlobalSkillsDir() {
+  return process.env.WIZZ_GLOBAL_SKILLS_DIR || path.join(os.homedir(), '.claude', 'skills');
+}
+
+// Verifica se os artefatos de que o roteamento depende de fato existem.
+// Devolve uma lista de avisos legíveis (vazia = tudo ok); nunca lança.
+function checkFallbackWarnings(isWizzProject, wizzRoot) {
+  const warnings = [];
+  try {
+    if (isWizzProject) {
+      const configPath = path.join(wizzRoot, '_wizz', 'config.toml');
+      if (!fs.existsSync(configPath)) {
+        warnings.push(`_wizz/config.toml não encontrado em ${wizzRoot} (install de projeto Wizz incompleto?)`);
+      }
+    } else {
+      const flatTablePath = path.join(getGlobalSkillsDir(), 'wizz-router', 'references', 'routing-table-flat.md');
+      if (!fs.existsSync(flatTablePath)) {
+        warnings.push(`routing-table-flat.md não encontrada em ${flatTablePath} — rode "npm run sync:global" no repo wizz-method`);
+      }
+    }
+  } catch {
+    // fail-silent — checagem de fallback nunca bloqueia o prompt
+  }
+  return warnings;
+}
+
+// Warning visível mesmo com trace desligado: fallback de roteamento é raro
+// e sinaliza um bug de sincronização (ex.: o próprio C1 da auditoria), então
+// vale a pena aparecer em stderr independente de WIZZ_TRACE.
+function emitFallbackWarnings(warnings) {
+  for (const warning of warnings) {
+    try {
+      process.stderr.write(`[wizz-router-enforce] fallback: ${warning}\n`);
+    } catch {
+      // fail-silent
+    }
+  }
+}
+
+function runHook() {
+  let input = '';
+  const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => (input += chunk));
+  process.stdin.on('end', () => {
+    clearTimeout(stdinTimeout);
+    try {
+      const data = JSON.parse(input);
+      const prompt = data.prompt || '';
+      const trivial = !prompt || isTrivial(prompt);
+      if (trivial) {
+        traceLine({ ts: new Date().toISOString(), isTrivial: true, mode: null });
+        process.exit(0);
+      }
+
+      const cwd = data.cwd || process.cwd();
+      const wizzRoot = findWizzRoot(cwd);
+      const isWizzProject = Boolean(wizzRoot);
+      const context = buildContext(isWizzProject);
+
+      const warnings = checkFallbackWarnings(isWizzProject, wizzRoot);
+      if (warnings.length > 0) emitFallbackWarnings(warnings);
+
+      traceLine({
+        ts: new Date().toISOString(),
+        isTrivial: false,
+        mode: isWizzProject ? 'wizz' : 'flat',
+        contextInjected: context,
+        warnings,
+      });
+
+      const output = {
+        hookSpecificOutput: {
+          hookEventName: 'UserPromptSubmit',
+          additionalContext: context,
+        },
+      };
+      process.stdout.write(JSON.stringify(output));
+    } catch {
+      // Falha em silêncio — nunca bloquear o prompt
+      process.exit(0);
+    }
+  });
+}
+
+if (require.main === module) {
+  runHook();
+} else {
+  module.exports = {
+    isTrivial,
+    buildContext,
+    findWizzRoot,
+    isTraceEnabled,
+    getTraceFile,
+    traceLine,
+    getGlobalSkillsDir,
+    checkFallbackWarnings,
+    emitFallbackWarnings,
+  };
+}

package/tools/installer/banner.js

@@ -29,7 +29,7 @@ const CLIUtils = {
 
     const logoLines = termWidth >= 95 ? logoWide : logoNarrow;
     const logo = logoLines.map((line) => color.blue(line)).join('\n');
-    const tagline = color.white('    Agile AI-Driven Development, the Wizz way\n    © Wizz! comms.  ·  Built on BMAD Core');
+    const tagline = color.white('    Método de agência orientado por IA\n    © Wizz! comms.  ·  method.wizzcomms.com');
 
     await prompts.box(`${logo}\n${tagline}`, '', {
       contentAlign: 'center',