wizz-method 2.0.0 → 2.1.0

package/tools/hooks/README.md

@@ -0,0 +1,22 @@
+# Hooks (fonte de verdade)
+
+Os hooks do Claude Code usados pelo Wizz Method vivem AQUI e são instalados em
+`~/.claude/hooks/` via `npm run sync:global`. Nunca edite a cópia global direto:
+ela é substituída no próximo sync.
+
+| Hook                            | Evento             | O que faz                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `wizz-router-enforce.js`        | UserPromptSubmit   | Gate `isTrivial()` + injeção curta: em projeto Wizz (`_wizz/`) manda delegar direto ao maestro/agente da área (sem router); fora, manda pro `wizz-router`.                                                                                                                                                                                                                                                                          |
+| `session-rules.js`              | SessionStart       | Duas coisas num processo só: injeta as regras de comunicação 1x por sessão (antes era por prompt) e resolve a FEATURE ATIVA sozinho (branch git > `_wizz/bmm/config.yaml` > nada), para ninguém precisar invocar `wizz-set-feature`. Branch de tronco e de release não viram feature; sem feature a linha não é emitida (custo zero). A feature também é o `tema` da memória.                                                       |
+| `security-defensive-context.js` | PreToolUse (Skill) | Metodologia defensiva/escopada ao invocar skills de segurança. Genérico por projeto (v2).                                                                                                                                                                                                                                                                                                                                           |
+| `rtk-rewrite.sh`                | PreToolUse (Bash)  | Reescreve comandos de shell via `rtk rewrite` (token economy). Fork local do hook gerado pelo instalador upstream do rtk, com 3 patches (auditoria 2026-07-07, C4/RT1; e 2026-09-11, RT-H3): reescrita linha a linha em comando multi-linha (o binário só reescrevia a 1ª linha), timeout interno por linha (`RTK_HOOK_TIMEOUT`, default 3s) que não depende do `timeout`/`gtimeout` do GNU coreutils, e cache do version-guard (`RTK_CACHE_TTL_SECONDS`, default 1h, em `${XDG_CACHE_HOME:-$HOME/.cache}/wizz/rtk-version`) pra não rodar `rtk --version` a cada `Bash` tool call da sessão. Requer `rtk` + `jq` no PATH; fail-open em ambos (e no cache: ilegível/corrompido/expirado recomputa em silêncio). |
+
+Removidos em 2026-07 (arquivados em `~/.claude/hooks-archive/`):
+`no-narration-enforce.js` (absorvido pelo session-rules) e `vault-reminder.js`.
+
+Testes: `npm run test:hooks` (isTrivial + contexto por modo), `npm run test:feature-context` (resolução da feature ativa: tronco não vira feature, branch ganha do config, silêncio quando não há feature) e `node test/test-rtk-hook.js` (rewrite básico + multi-linha do `rtk-rewrite.sh`, smoke test que exercita o binário `rtk` real quando disponível, e o cache do version-guard: criado na 1ª chamada e reusado na 2ª, TTL expirado força recompute, path do binário mudou invalida, cache corrompido não quebra e se auto-cura).
+Evals de roteamento: `node evals/routing/run-routing-eval.mjs [--llm]`.
+
+Drift repo ↔ global: `npm run sync:check` compara hash de cada hook (e skill) entre o repo e `~/.claude`, sem escrever nada — é lembrete (fail-open), não gate; roda no fim do `npm test`. Achou drift? `npm run sync:global` atualiza `~/.claude`.
+
+Registro por projeto (RT-C1, item 3): o installer copia estes hooks para `_wizz/hooks/` de cada projeto instalado e registra a chamada em `.claude/settings.json` do projeto, via merge puro em `tools/installer/core/hooks-settings.js`. Antes de registrar, ele lê o `settings.json` GLOBAL do usuário (`~/.claude/settings.json`, ou o path apontado por `WIZZ_GLOBAL_SETTINGS_FILE` quando definido) e pula qualquer hook nosso que já esteja registrado lá no mesmo evento, para não rodar o mesmo hook 2x numa máquina onde o mantenedor já fez o registro global (decisão do dono, 2026-09-11). Settings global ausente ou com JSON inválido não filtra nada.

package/tools/hooks/rtk-rewrite.sh

@@ -0,0 +1,280 @@
+#!/usr/bin/env bash
+# rtk-hook-version: 3-wizz3
+# RTK Claude Code hook — rewrites commands to use rtk for token savings.
+# Requires: rtk >= 0.23.0, jq
+#
+# Fonte de verdade: tools/hooks/rtk-rewrite.sh neste repo. Instalado em
+# ~/.claude/hooks/ via `npm run sync:global` (nunca editar a cópia global
+# direto: ela é substituída no próximo sync). Isto é um FORK local do hook
+# gerado pelo instalador upstream do rtk (que documenta "single source of
+# truth = src/discover/registry.rs, não edite este arquivo"): mantemos a
+# delegação da lógica de rewrite pro binário `rtk rewrite`, mas aplicamos 3
+# patches locais que o upstream não tem (auditoria 2026-07-07, C4/RT1; e
+# auditoria 2026-09-11, RT-H3):
+#
+#   1. Bug de comando multi-linha: `rtk rewrite` (confirmado ainda presente
+#      no binário 0.43.0, reportado
+#      upstream) só reescreve a 1ª linha de um comando multi-linha; as
+#      demais passam cruas, sem aviso, gerando saída mista. Correção: este
+#      hook detecta comando multi-linha e chama `rtk rewrite` LINHA A LINHA,
+#      preservando a reescrita completa em vez de só a primeira linha.
+#   2. Timeout interno por linha (RTK_HOOK_TIMEOUT, default 3s): evita que
+#      uma chamada travada a `rtk rewrite` prenda o prompt inteiro. Não
+#      depende do `timeout`/`gtimeout` do GNU coreutils (ausente por padrão
+#      no macOS) — usa um watcher em background portátil (bash puro).
+#      Isso é além do timeout de 5s já configurado no bloco PreToolUse do
+#      settings.json (defesa em profundidade, não substituição).
+#   3. Cache do version-guard (RTK_CACHE_TTL_SECONDS, default 1h): sem isso
+#      o guard rodava `rtk --version` + parsing a CADA Bash tool call da
+#      sessão (5 spawns/chamada). Ver comentário em `rtk_version_ok` abaixo
+#      para o formato do cache e o motivo do diretório escolhido.
+#
+# Version guard (floor de compatibilidade do subcomando `rewrite`, 0.23.0):
+# é diferente do pin de supply chain do registry (`cli_utility.rtk`, hoje
+# v0.43.0) — aquele controla o que o installer OFERECE instalar; este
+# controla o que ESTE hook aceita rodar sem quebrar.
+
+RTK_HOOK_TIMEOUT="${RTK_HOOK_TIMEOUT:-3}"
+
+# Cache do version-guard (RT-H3, auditoria 2026-09-11): sem cache, o guard
+# de versão rodava `rtk --version` + `grep` + `head` + 2x `cut` (5 spawns)
+# a CADA Bash tool call da sessão inteira, só pra confirmar um dado que não
+# muda no meio da sessão. Agora fica em cache com TTL de 1h, invalidado
+# também se o binário `rtk` do PATH mudar de lugar (upgrade/reinstall no
+# meio da sessão).
+#
+# Local do cache: ${XDG_CACHE_HOME:-$HOME/.cache}/wizz/rtk-version.
+# XDG_CACHE_HOME é o padrão em Linux e cada vez mais respeitado em macOS
+# também (Homebrew, uv, Docker Desktop já escrevem em ~/.cache); cai pra
+# $HOME/.cache quando ausente, que existe nas duas plataformas — mais
+# portátil que hardcodar um dos dois. Preferido a ${TMPDIR:-/tmp}: TMPDIR
+# é o certo pra artefato descartável de UM processo, mas o objetivo aqui é
+# sobreviver a Bash calls dentro da mesma sessão (e entre sessões, já que a
+# versão instalada muda raramente) — cache "de configuração", não "de
+# processo". Conteúdo não é sensível (só path do binário, status ok/old e
+# timestamp), então não precisa do isolamento por-UID que TMPDIR daria.
+RTK_CACHE_TTL_SECONDS="${RTK_CACHE_TTL_SECONDS:-3600}"
+RTK_CACHE_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/wizz"
+RTK_CACHE_FILE="$RTK_CACHE_DIR/rtk-version"
+
+if ! command -v jq &>/dev/null; then
+  echo "[rtk] WARNING: jq is not installed. Hook cannot rewrite commands. Install jq: https://jqlang.github.io/jq/download/" >&2
+  exit 0
+fi
+
+if ! command -v rtk &>/dev/null; then
+  echo "[rtk] WARNING: rtk is not installed or not in PATH. Hook cannot rewrite commands. Install: https://github.com/rtk-ai/rtk#installation" >&2
+  exit 0
+fi
+
+# rtk_version_ok — true (exit 0) quando o `rtk` do PATH é >= 0.23.0 (piso de
+# compatibilidade do subcomando `rewrite`). Resultado cacheado em
+# $RTK_CACHE_FILE por $RTK_CACHE_TTL_SECONDS; cache ilegível, corrompido,
+# expirado, ou com path de binário diferente do atual é ignorado em
+# silêncio e recomputado — fail-open, mesma filosofia do resto do hook: um
+# cache ruim nunca deve travar o rewrite, só custar 1 recomputo.
+#
+# Caminho quente (cache válido): zero spawns — `command -v` é builtin do
+# bash, `read` lê o arquivo sem subshell, e `$EPOCHSECONDS` (bash >= 5,
+# padrão no macOS/Linux modernos) evita o spawn de `date`; em bash < 5 cai
+# pra `date +%s` (1 spawn). Caminho frio (cache ausente/expirado, ~1x/h):
+# `rtk --version` + `mktemp` + `mv` (3 spawns, contra 5 de antes, e só uma
+# vez por hora em vez de a cada comando).
+rtk_version_ok() {
+  local rtk_path cached_path cached_status cached_ts now elapsed
+  rtk_path=$(command -v rtk)
+  now="${EPOCHSECONDS:-$(date +%s)}"
+
+  if [ -r "$RTK_CACHE_FILE" ]; then
+    IFS=$'\t' read -r cached_path cached_status cached_ts _ <"$RTK_CACHE_FILE" 2>/dev/null
+    case "$cached_ts" in
+      '' | *[!0-9]*) cached_ts="" ;;
+    esac
+    if [ -n "$cached_ts" ] && [ "$cached_path" = "$rtk_path" ] &&
+      { [ "$cached_status" = "ok" ] || [ "$cached_status" = "old" ]; }; then
+      elapsed=$((now - cached_ts))
+      if [ "$elapsed" -ge 0 ] && [ "$elapsed" -lt "$RTK_CACHE_TTL_SECONDS" ]; then
+        [ "$cached_status" = "ok" ]
+        return $?
+      fi
+    fi
+  fi
+
+  # Cache ausente/corrompido/expirado/binário mudou: recomputa (1 spawn:
+  # `rtk --version`). Extração de X.Y.Z via builtins (case + parameter
+  # expansion), sem grep/cut, equivalente ao antigo
+  # `grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1` + `cut -d. -f1/f2`.
+  local version_line word vnum major minor status
+  version_line=$(rtk --version 2>/dev/null)
+  status="ok"
+  vnum=""
+  for word in $version_line; do
+    case "$word" in
+      v[0-9]*.[0-9]*.[0-9]*) word="${word#v}" ;;
+    esac
+    case "$word" in
+      [0-9]*.[0-9]*.[0-9]*)
+        vnum="$word"
+        break
+        ;;
+    esac
+  done
+  if [ -n "$vnum" ]; then
+    major="${vnum%%.*}"
+    minor="${vnum#*.}"
+    minor="${minor%%.*}"
+    case "$major" in '' | *[!0-9]*) major=0 ;; esac
+    case "$minor" in '' | *[!0-9]*) minor=0 ;; esac
+    # Require >= 0.23.0
+    if [ "$major" -eq 0 ] && [ "$minor" -lt 23 ]; then
+      status="old"
+      echo "[rtk] WARNING: rtk $vnum is too old (need >= 0.23.0). Upgrade: cargo install rtk" >&2
+    fi
+  fi
+
+  # Escrita atômica (tmp + mv no mesmo dir): qualquer falha (dir não
+  # gravável, disco cheio, /tmp somente-leitura) é ignorada — o cache é só
+  # uma otimização, nunca uma dependência.
+  if mkdir -p "$RTK_CACHE_DIR" 2>/dev/null; then
+    local tmp
+    tmp=$(mktemp "$RTK_CACHE_DIR/.rtk-version.XXXXXX" 2>/dev/null) && {
+      printf '%s\t%s\t%s\n' "$rtk_path" "$status" "$now" >"$tmp" 2>/dev/null &&
+        mv -f "$tmp" "$RTK_CACHE_FILE" 2>/dev/null
+      rm -f "$tmp" 2>/dev/null
+    }
+  fi
+
+  [ "$status" = "ok" ]
+}
+
+if ! rtk_version_ok; then
+  exit 0
+fi
+
+# multiline_unsafe <cmd> — retorna 0 (unsafe) quando reescrever linha a
+# linha pode corromper o comando: heredoc (linhas de corpo que parecem
+# comando seriam reescritas, ex. `git status` dentro de `cat <<EOF`),
+# continuação com `\` no fim da linha (a linha seguinte é argumento, não
+# comando) ou aspas desbalanceadas numa linha (string atravessa a quebra).
+# Nesses casos o comando passa INTACTO (fail-open), sem reescrita parcial.
+multiline_unsafe() {
+  local cmd="$1"
+  case "$cmd" in
+    *"<<"*) return 0 ;;
+  esac
+  local line dq sq
+  while IFS= read -r line || [ -n "$line" ]; do
+    case "$line" in
+      *\\) return 0 ;;
+    esac
+    dq=$(printf '%s' "$line" | tr -cd '"' | wc -c)
+    sq=$(printf '%s' "$line" | tr -cd "'" | wc -c)
+    if [ $((dq % 2)) -ne 0 ] || [ $((sq % 2)) -ne 0 ]; then
+      return 0
+    fi
+  done <<RTK_HOOK_GUARD_EOF
+$cmd
+RTK_HOOK_GUARD_EOF
+  return 1
+}
+
+# rewrite_one <line> — imprime a linha reescrita, limitada por
+# RTK_HOOK_TIMEOUT segundos. Em timeout ou qualquer falha do rtk, imprime a
+# linha original sem alteração (fail-open, mesma filosofia do resto do hook).
+rewrite_one() {
+  local line="$1"
+  if [ -z "$line" ]; then
+    printf '%s' ''
+    return 0
+  fi
+  local tmp
+  tmp=$(mktemp 2>/dev/null) || {
+    printf '%s' "$line"
+    return 0
+  }
+  ( rtk rewrite "$line" >"$tmp" 2>/dev/null ) &
+  local pid=$!
+  # O watcher roda com stdout/stderr em /dev/null: esta função é chamada
+  # dentro de $(...), e um filho que herdasse o pipe da substituição de
+  # comando seguraria o chamador até o `sleep` terminar (3 s por chamada,
+  # mesmo com o rtk respondendo em ms). O trap mata o `sleep` quando o
+  # watcher recebe TERM, para não sobrar um kill tardio num pid reciclado.
+  (
+    trap 'kill "$sleeper" 2>/dev/null; exit 0' TERM
+    sleep "$RTK_HOOK_TIMEOUT" &
+    sleeper=$!
+    wait "$sleeper"
+    kill -TERM "$pid" 2>/dev/null
+  ) >/dev/null 2>&1 &
+  local watcher=$!
+  wait "$pid" 2>/dev/null
+  local status=$?
+  kill -TERM "$watcher" 2>/dev/null
+  wait "$watcher" 2>/dev/null
+
+  # Exit codes do `rtk rewrite`: 0 = reescrito (≤0.30.x), 3 = reescrito
+  # (0.43.0+, apesar do --help ainda dizer 0), 1 = sem equivalente (sem
+  # output). Qualquer outro status (timeout/SIGTERM=143, erro) = fail-open.
+  if { [ "$status" -eq 0 ] || [ "$status" -eq 3 ]; } && [ -s "$tmp" ]; then
+    cat "$tmp"
+  else
+    printf '%s' "$line"
+  fi
+  rm -f "$tmp" 2>/dev/null
+}
+
+INPUT=$(cat)
+CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+
+if [ -z "$CMD" ]; then
+  exit 0
+fi
+
+case "$CMD" in
+  *$'\n'*)
+    # Comando multi-linha: reescreve linha a linha (bug RT1/C4), exceto
+    # quando o guard detecta risco de corrupção (heredoc, continuação,
+    # string multi-linha) — aí passa intacto. O heredoc do loop (não um
+    # pipe) garante que ele roda no shell atual, não numa subshell, para
+    # REWRITTEN sobreviver ao loop.
+    if multiline_unsafe "$CMD"; then
+      exit 0
+    fi
+    REWRITTEN=""
+    first=1
+    while IFS= read -r line || [ -n "$line" ]; do
+      rewritten_line=$(rewrite_one "$line")
+      if [ "$first" -eq 1 ]; then
+        REWRITTEN="$rewritten_line"
+        first=0
+      else
+        REWRITTEN="$REWRITTEN
+$rewritten_line"
+      fi
+    done <<RTK_HOOK_EOF
+$CMD
+RTK_HOOK_EOF
+    ;;
+  *)
+    REWRITTEN=$(rewrite_one "$CMD")
+    ;;
+esac
+
+# No change — nothing to do.
+if [ "$CMD" = "$REWRITTEN" ]; then
+  exit 0
+fi
+
+ORIGINAL_INPUT=$(echo "$INPUT" | jq -c '.tool_input')
+UPDATED_INPUT=$(echo "$ORIGINAL_INPUT" | jq --arg cmd "$REWRITTEN" '.command = $cmd')
+
+jq -n \
+  --argjson updated "$UPDATED_INPUT" \
+  '{
+    "hookSpecificOutput": {
+      "hookEventName": "PreToolUse",
+      "permissionDecision": "allow",
+      "permissionDecisionReason": "RTK auto-rewrite",
+      "updatedInput": $updated
+    }
+  }'

package/tools/hooks/security-defensive-context.js

@@ -0,0 +1,70 @@
+/**
+ * security-defensive-context.js
+ *
+ * Fonte de verdade: wizz-method/tools/hooks/. Instalar via `npm run sync:global`.
+ *
+ * Hook PreToolUse: quando o usuário invoca uma skill de segurança, injeta
+ * instruções de metodologia que orientam o modelo a trabalhar de forma
+ * defensiva, escopada e por dimensão — evitando o padrão de varredura ampla
+ * que aciona os safeguards de cibersegurança da Anthropic.
+ *
+ * v2 (2026-07): contexto genérico por projeto (a v1 hardcodava o stack do MeJu
+ * e injetava esse contexto em QUALQUER projeto).
+ *
+ * IMPORTANTE: guia o COMPORTAMENTO DO MODELO (abordagem + metodologia). Não
+ * desativa nem bypassa o safeguard da Anthropic — isso é impossível por hook.
+ */
+
+const SECURITY_SKILLS = new Set([
+  // Skills globais instaladas em ~/.claude/skills/
+  'wizz-web-security',
+  'wizz-desktop-security',
+  // Skills providas por plugins (nomes canônicos verificados)
+  'security-review',
+  'security-reviewer',
+  'security-scan',
+  // code-review em variantes de plugin e direto
+  'code-review',
+  'code-review:code-review',
+]);
+
+const DEFENSIVE_CONTEXT =
+  'Metodologia de revisao de seguranca (defensiva, escopada):\n\n' +
+  '1. ESCOPO: trabalhe por arquivo ou dimensao concreta de cada vez (ex: validacao ' +
+  'de entrada num handler, politicas de acesso do banco, headers HTTP). Nunca ' +
+  'varredura ampla de todo o codebase num turno unico.\n\n' +
+  '2. FOCO DEFENSIVO: o objetivo e hardening do codigo do proprio projeto. Cada ' +
+  'achado deve mapear para uma linha/arquivo real e propor a correcao aplicada localmente.\n\n' +
+  '3. DIMENSOES PRIORITARIAS (adapte ao stack do projeto atual): (a) auth/sessao; ' +
+  '(b) validacao/allowlist de entrada em handlers de escrita; (c) autorizacao no ' +
+  'banco (RLS/policies) e funcoes privilegiadas; (d) privacidade LGPD/GDPR — PII, ' +
+  'consentimento, retencao; (e) secrets — nada hardcoded em settings/migrations/logs; ' +
+  '(f) superficie publica — rate-limit, headers de seguranca, CORS.\n\n' +
+  '4. OUTPUT: achados por severidade (CRITICO / ALTO / MEDIO / BAIXO), com arquivo + ' +
+  'linha + codigo corrigido sugerido. Nao gerar relatorio ofensivo nem exploits.';
+
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => (raw += chunk));
+process.stdin.on('end', () => {
+  try {
+    const payload = JSON.parse(raw);
+    const toolName = payload.tool_name || '';
+    const skillName = (payload.tool_input && payload.tool_input.skill) || '';
+
+    if (toolName === 'Skill' && SECURITY_SKILLS.has(skillName)) {
+      process.stdout.write(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            additionalContext: DEFENSIVE_CONTEXT,
+          },
+        }),
+      );
+    }
+    // Para qualquer outra skill/tool: sai silenciosamente sem output
+  } catch {
+    // Parse error: sai silenciosamente, nao bloqueia nada
+  }
+  process.exit(0);
+});