wizz-method 2.18.0 → 2.19.1

package/tools/hooks/README.md

@@ -4,29 +4,33 @@ 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. Fora de projeto Wizz e sem branch de feature a linha não é emitida (custo zero); dentro de projeto Wizz sem feature sai o lembrete curto "o primeiro pedido nomeado define uma", e sem `layout:` o lembrete de propor um. 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).                                                                                                                                                                                                                                                                                                                                           |
-| `wizz-artifact-guard.js`        | PostToolUse (Write) | Avisa (nunca bloqueia) artefato escrito fora da subpasta da feature ativa, artefato de feature sem feature ativa, frontmatter faltando em `<tipo>-<slug>.md`, e arquivo solto na raiz fora do `layout:`, com o comando que move. Fail-open sem `_wizz/` ou config. |
-| `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). |
+| 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. Fora de projeto Wizz e sem branch de feature a linha não é emitida (custo zero); dentro de projeto Wizz sem feature sai o lembrete curto "o primeiro pedido nomeado define uma", e sem `layout:` o lembrete de propor um. 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).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `wizz-artifact-guard.js`        | PostToolUse (Write/Edit) | Avisa (nunca bloqueia) artefato escrito fora da subpasta da feature ativa, artefato de feature sem feature ativa, frontmatter faltando em `<tipo>-<slug>.md`, e arquivo solto na raiz fora do `layout:`, com o comando que move. Fail-open sem `_wizz/` ou config.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `wizz-close-reminder.js`        | Stop                     | Aviso ao usuário (`systemMessage`, nunca `decision: block`) quando a feature ativa está `implementado`/`no-ar` e o checklist de fechamento do `wizz-feature.js` tem pendência (ou está no ar e segue ativa). Sem subprocesso, sai cedo fora de projeto Wizz e com feature em andamento, não repete o mesmo aviso na sessão, fail-open.                                                                                                                                                                                                                                                                                                                                                                          |
+| `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). |
+| `rtk-rewrite.js`                | PreToolUse (Bash)        | Versão Node do `rtk-rewrite.sh`, registrada no lugar dele só no Windows (sem bash e jq garantidos lá), desde 2026-10-15. Mesmo contrato: guard de multi-linha, linha a linha, timeout por linha, piso 0.23.0, fail-open. Sem o cache de versão. `node test/test-rtk-hook-node.js` exige a mesma saída dos dois contra o mesmo `rtk` fake. |
 
 Arquivos de apoio (copiados junto, NUNCA registrados em settings.json; o doctor cobra a presença):
 
-| Arquivo | O que é |
-| --- | --- |
-| `wizz-feature-lib.js` | Funções puras de feature, git, config, pastas de artefato e frontmatter. Usada por todos os hooks acima. |
-| `wizz-layout-lib.js` | O que pode ficar na raiz e para onde vai o resto (tipos `codigo`, `scripts`, `dados`, `docs`, `midia`, `arquivo`). |
-| `wizz-feature.js` | CLI do ciclo de vida da feature: `resolver`, `definir`, `artefato`, `decidir`, `status`, `verificar`, `encerrar`, `listar`. É o passo verificável que router/maestro rodam antes de despachar. |
-| `wizz-arrumar.js` | CLI de arrumação: `layout [--gravar]`, `planejar`, `aplicar` (manifesto .tsv + referências + testes antes/depois + `desfazer.sh`), `mover`, `desfazer`. |
+| Arquivo               | O que é                                                                                                                                                                                                                                                                                                                       |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `wizz-feature-lib.js` | Funções puras de feature, git, config, pastas de artefato e frontmatter. Usada por todos os hooks acima.                                                                                                                                                                                                                      |
+| `wizz-layout-lib.js`  | O que pode ficar na raiz e para onde vai o resto (tipos `codigo`, `scripts`, `dados`, `docs`, `midia`, `arquivo`).                                                                                                                                                                                                            |
+| `wizz-cerebro-lib.js` | Grava o fechamento no Cérebro (`encerrar --cerebro`): acha o vault e `projetos/<projeto>.md`, atualiza a linha da feature e a `Última sessão` do bloco Estado e põe 1 linha em Sessões (teto 15; as antigas vão para `_index/cerebro-archive.md`, lido só por grep). Idempotente, fail-open.                                  |
+| `wizz-debug-lib.js`   | Diagnóstico opt-in dos hooks: com `WIZZ_DEBUG=1` cada erro engolido vira 1 linha em stderr e é anexada a `~/.claude/wizz-debug.log` (`WIZZ_DEBUG_FILE` troca o caminho). Sem a variável: zero saída, zero disco. Os hooks seguem fail-open (exit 0). O `wizz doctor` roda cada hook com esse modo ligado (check `hooks-run`). |
+| `wizz-feature.js`     | CLI do ciclo de vida da feature: `resolver`, `definir`, `artefato`, `decidir`, `status`, `verificar`, `encerrar [--cerebro]`, `listar`. É o passo verificável que router/maestro rodam antes de despachar.                                                                                                                    |
+| `wizz-arrumar.js`     | CLI de arrumação: `layout [--gravar]`, `planejar`, `aplicar` (manifesto .tsv + referências + testes antes/depois + `desfazer.sh`), `mover`, `desfazer`.                                                                                                                                                                       |
 
 Regra completa em `src/modules/wizz/_shared/organizacao.md` (2026-10-02, caso Spider). `session-rules.js` passou a lembrar "nenhuma feature ativa" e "projeto sem layout" dentro de projeto Wizz, e `wizz-router-enforce.js` acrescenta 1 linha de feature por prompt em projeto Wizz.
 
 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:organizacao` (CLIs de feature e arrumação, guard, lembretes nos cenários sem git / main / branch), `npm run eval:feature` (hooks reais + CLI + estado final; `--llm` mede a obediência do modelo), `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).
+Testes: `node test/test-feature-close.js` (`encerrar --cerebro` e o lembrete do Stop), `npm run test:organizacao` (CLIs de feature e arrumação, guard, lembretes nos cenários sem git / main / branch), `npm run eval:feature` (hooks reais + CLI + estado final; `--llm` mede a obediência do modelo), `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`.

package/tools/hooks/rtk-rewrite.js

@@ -0,0 +1,95 @@
+// rtk-rewrite.js — PreToolUse (Bash): reescreve o comando via `rtk rewrite`.
+//
+// Versão Node do rtk-rewrite.sh para o Windows (2026-10-15), onde não há bash
+// nem jq garantidos. O installer registra este arquivo em win32 e o .sh nos
+// outros sistemas (hooks-settings.js), então o comportamento tem de ser o
+// mesmo; test/test-rtk-hook-node.js roda os dois contra o mesmo rtk fake.
+//
+// Mesmo contrato do .sh:
+//   - sem rtk no PATH, ou rtk abaixo de 0.23.0: sai 0 sem tocar o comando;
+//   - comando multi-linha com heredoc, continuação `\` ou aspas abertas numa
+//     linha passa intacto (reescrever corromperia o corpo do heredoc);
+//   - cada linha vai sozinha para `rtk rewrite`, com timeout (RTK_HOOK_TIMEOUT,
+//     3 s); exit 0 ou 3 com saída = linha nova, qualquer outra coisa = original;
+//   - nada mudou: stdout vazio. Mudou: hookSpecificOutput com updatedInput.
+// Fail-open em tudo: erro aqui nunca bloqueia o Bash.
+//
+// Sem o cache de versão do .sh: `rtk --version` de um binário nativo custa
+// poucos ms, e no Windows não há `command -v` para chavear o cache pelo path.
+
+const { spawnSync } = require('node:child_process');
+
+const TIMEOUT_MS = (Number(process.env.RTK_HOOK_TIMEOUT) || 3) * 1000;
+const FLOOR = [0, 23];
+
+function rtkVersionOk() {
+  const res = spawnSync('rtk', ['--version'], { encoding: 'utf8', timeout: TIMEOUT_MS, windowsHide: true });
+  if (res.error || res.status !== 0) {
+    process.stderr.write('[rtk] WARNING: rtk is not installed or not in PATH. Hook cannot rewrite commands.\n');
+    return false;
+  }
+  const match = /v?(\d+)\.(\d+)\.(\d+)/.exec(res.stdout || '');
+  if (!match) return true;
+  const [major, minor] = [Number(match[1]), Number(match[2])];
+  if (major === FLOOR[0] && minor < FLOOR[1]) {
+    process.stderr.write(
+      `[rtk] WARNING: rtk ${match[1]}.${match[2]}.${match[3]} is too old (need >= 0.23.0). Upgrade: cargo install rtk\n`,
+    );
+    return false;
+  }
+  return true;
+}
+
+// Heredoc, continuação ou aspas desbalanceadas numa linha: não dá para
+// reescrever linha a linha sem quebrar o comando.
+function multilineUnsafe(cmd) {
+  if (cmd.includes('<<')) return true;
+  return cmd.split('\n').some((line) => {
+    if (line.endsWith('\\')) return true;
+    const count = (ch) => line.split(ch).length - 1;
+    return count('"') % 2 !== 0 || count("'") % 2 !== 0;
+  });
+}
+
+function rewriteOne(line) {
+  if (!line) return line;
+  const res = spawnSync('rtk', ['rewrite', line], { encoding: 'utf8', timeout: TIMEOUT_MS, windowsHide: true });
+  // Como o $(...) do .sh: a saída perde só as quebras de linha do fim.
+  const out = (res.stdout || '').replace(/\n+$/, '');
+  return !res.error && (res.status === 0 || res.status === 3) && out ? out : line;
+}
+
+function main(raw) {
+  const input = JSON.parse(raw);
+  const toolInput = input && typeof input.tool_input === 'object' && input.tool_input ? input.tool_input : {};
+  const cmd = typeof toolInput.command === 'string' ? toolInput.command : '';
+  if (!cmd) return;
+  if (cmd.includes('\n') && multilineUnsafe(cmd)) return;
+  if (!rtkVersionOk()) return;
+
+  const rewritten = cmd.includes('\n') ? cmd.split('\n').map(rewriteOne).join('\n') : rewriteOne(cmd);
+  if (rewritten === cmd) return;
+
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'allow',
+        permissionDecisionReason: 'RTK auto-rewrite',
+        updatedInput: { ...toolInput, command: rewritten },
+      },
+    }) + '\n',
+  );
+}
+
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => (raw += chunk));
+process.stdin.on('end', () => {
+  try {
+    main(raw);
+  } catch {
+    // fail-open: JSON quebrado ou erro inesperado deixa o comando como veio
+  }
+  process.exit(0);
+});

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

@@ -28,6 +28,21 @@ const SECURITY_SKILLS = new Set([
   'code-review:code-review',
 ]);
 
+// 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('security-defensive-context', 'require wizz-debug-lib', error);
+}
+
 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 ' +
@@ -63,8 +78,9 @@ process.stdin.on('end', () => {
       );
     }
     // Para qualquer outra skill/tool: sai silenciosamente sem output
-  } catch {
+  } catch (error) {
     // Parse error: sai silenciosamente, nao bloqueia nada
+    debug('security-defensive-context', 'parse payload', error);
   }
   process.exit(0);
 });

package/tools/hooks/session-rules.js

@@ -45,11 +45,27 @@ const RULES =
 // Feature, git e config moram em wizz-feature-lib.js (mesma pasta: o installer
 // e o sync:global copiam tools/hooks/ inteiro). Se a lib faltar numa cópia
 // manual parcial, a regra de comunicação continua saindo e a feature cala.
+// 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('session-rules', 'require wizz-debug-lib', error);
+}
+
 let lib = null;
 try {
   lib = require('./wizz-feature-lib.js');
-} catch {
+} catch (error) {
   lib = null;
+  debug('session-rules', 'require wizz-feature-lib', error);
 }
 
 const HOOK_CMD = 'node _wizz/hooks/wizz-feature.js';
@@ -246,22 +262,25 @@ function finish(raw) {
   try {
     const payload = JSON.parse(raw || '{}');
     if (payload && typeof payload.cwd === 'string' && payload.cwd) cwd = payload.cwd;
-  } catch {
+  } catch (error) {
     // payload ausente ou inválido: cai no cwd do processo
+    debug('session-rules', 'parse payload', error);
   }
 
   try {
     const feature = buildFeatureContext(cwd);
     if (feature) context += `\n\n${feature}`;
-  } catch {
+  } catch (error) {
     // resolução de feature NUNCA derruba as regras de comunicação
+    debug('session-rules', 'buildFeatureContext', error);
   }
 
   try {
     const ceiling = buildMemoryCeilingContext(cwd);
     if (ceiling) context += `\n\n${ceiling}`;
-  } catch {
+  } catch (error) {
     // teto da memória é aviso, não gate: erro aqui não afeta o resto
+    debug('session-rules', 'buildMemoryCeilingContext', error);
   }
 
   try {
@@ -273,8 +292,9 @@ function finish(raw) {
         },
       }),
     );
-  } catch {
+  } catch (error) {
     // nunca bloquear
+    debug('session-rules', 'write stdout', error);
   }
   process.exit(0);
 }

package/tools/hooks/wizz-arrumar.js

@@ -14,8 +14,10 @@
 //   mover <origem> <destino> atalho de um arquivo (manifesto de uma linha + aplicar)
 //   desfazer <pasta-da-arrumacao>
 //
-// Opções de aplicar/mover: --testes "<comando>", --refs <dir,dir> (ex.: pasta
-// da auto-memória), --manter (não desfaz sozinho se os testes quebrarem).
+// Opções de aplicar/mover: --testes "<comando>" (só runner conhecido: npm/pnpm/
+// yarn/bun test, npx vitest|jest, pytest, go/cargo/make test; sem valor = script
+// test do package.json; outro comando exige --testes-livre), --refs <dir,dir>
+// (ex.: pasta da auto-memória), --manter (não desfaz sozinho se os testes quebrarem).
 // Cada execução fica em `<arquivo>/arrumacao/<data>-<hora>/`.
 
 const fs = require('node:fs');
@@ -76,7 +78,7 @@ function parseArgs(argv) {
     if (a.startsWith('--')) {
       const key = a.slice(2);
       const next = argv[i + 1];
-      if (next !== undefined && !next.startsWith('--')) {
+      if (key !== 'testes-livre' && next !== undefined && !next.startsWith('--')) {
         opts[key] = next;
         i++;
       } else opts[key] = true;
@@ -237,17 +239,116 @@ function rewriteRefs(text, moves, fileDir) {
 
 // ── aplicar / desfazer ──────────────────────────────────────────────────
 
-function runTests(root, cmd) {
-  if (!cmd || cmd === true) return null;
-  const r = spawnSync(cmd, { cwd: root, shell: true, encoding: 'utf8', timeout: 10 * 60 * 1000 });
-  return { ok: r.status === 0, code: r.status, tail: `${r.stdout || ''}${r.stderr || ''}`.trim().split('\n').slice(-5).join('\n') };
+// ── comando de testes: allowlist, sem shell ─────────────────────────────
+//
+// `--testes` não executa string arbitrária: o comando é cortado em argv (sem
+// shell) e só roda se for de um runner conhecido. `--testes` sem valor usa o
+// script `test` do package.json. Qualquer outra coisa exige `--testes-livre`,
+// que imprime o que vai rodar e usa o shell (o dono assumiu o comando).
+
+const SHELL_META = /[;&|<>$`()\n\r\\]/;
+const PM = new Set(['npm', 'pnpm', 'yarn', 'bun']);
+const TEST_SCRIPT = /^test(?:[:\w.-]*)$/;
+
+/** Corta em argv respeitando aspas simples/duplas. null = não dá para cortar com segurança. */
+function splitArgv(text) {
+  if (SHELL_META.test(text)) return null;
+  const argv = [];
+  let cur = '';
+  let quote = '';
+  let has = false;
+  for (const ch of text) {
+    if (quote) {
+      if (ch === quote) quote = '';
+      else cur += ch;
+    } else if (ch === '"' || ch === "'") {
+      quote = ch;
+      has = true;
+    } else if (/\s/.test(ch)) {
+      if (has || cur) argv.push(cur);
+      cur = '';
+      has = false;
+    } else {
+      cur += ch;
+      has = true;
+    }
+  }
+  if (quote) return null;
+  if (has || cur) argv.push(cur);
+  return argv;
+}
+
+/** O argv é de um runner de testes conhecido? */
+function isAllowedTestArgv(argv) {
+  const [bin, a, b] = argv;
+  if (!bin) return false;
+  if (PM.has(bin)) return a === 'test' || (a === 'run' && TEST_SCRIPT.test(b || ''));
+  if (bin === 'npx') return a === 'vitest' || a === 'jest';
+  if (bin === 'pytest') return true;
+  if (bin === 'python' || bin === 'python3') return a === '-m' && (b === 'pytest' || b === 'unittest');
+  if (bin === 'go' || bin === 'cargo' || bin === 'make') return a === 'test';
+  return false;
+}
+
+/**
+ * Resolve o que `--testes` vai rodar.
+ * @returns {{none: true}|{argv: string[], shell: false, display: string}|{shellCmd: string, shell: true, display: string}|{error: string}}
+ */
+function resolveTestCommand(root, opts) {
+  const raw = opts.testes;
+  if (!raw) return { none: true };
+  let text = raw;
+  if (raw === true) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+      if (!pkg.scripts || typeof pkg.scripts.test !== 'string') throw new Error('sem script test');
+    } catch {
+      return {
+        error: '--testes sem comando pede o script "test" do package.json, e ele não existe aqui. Passe o comando ou use --testes-livre.',
+      };
+    }
+    text = 'npm test';
+  }
+  const argv = splitArgv(text);
+  if (argv && isAllowedTestArgv(argv)) return { argv, shell: false, display: argv.join(' ') };
+  if (opts['testes-livre']) return { shellCmd: text, shell: true, display: text };
+  return {
+    error:
+      `Comando de testes fora da lista: "${text}". Aceitos: npm/pnpm/yarn/bun test ou run test*, npx vitest|jest, pytest, ` +
+      'python -m pytest|unittest, go test, cargo test, make test (sem ; & | < > $ ` ou parênteses). ' +
+      'Para rodar outro comando, repita com --testes-livre.',
+  };
+}
+
+function runTests(root, resolved) {
+  if (!resolved || resolved.none) return null;
+  process.stderr.write(`Rodando testes${resolved.shell ? ' (livre, via shell)' : ''}: ${resolved.display}\n`);
+  const timeout = 10 * 60 * 1000;
+  const r = resolved.shell
+    ? spawnSync(resolved.shellCmd, { cwd: root, shell: true, encoding: 'utf8', timeout })
+    : spawnSync(resolved.argv[0], resolved.argv.slice(1), { cwd: root, shell: false, encoding: 'utf8', timeout });
+  const out = `${r.stdout || ''}${r.stderr || ''}${r.error ? r.error.message : ''}`;
+  return { ok: r.status === 0, code: r.status, tail: out.trim().split('\n').slice(-5).join('\n') };
 }
 
 function shQuote(s) {
   return `'${String(s).replaceAll("'", String.raw`'\''`)}'`;
 }
 
-function writeUndoScript(runDir, root, moves, edits) {
+// Desfazer em qualquer sistema: `node wizz-arrumar.js desfazer <pasta>` (Node
+// puro, função undo abaixo). O script ao lado é atalho: desfazer.sh fora do
+// Windows; no Windows, sem bash garantido, um desfazer.cmd que chama o Node.
+function undoCommand(root, runDir) {
+  const q = (p) => `"${p}"`;
+  return `node ${q(__filename)} desfazer ${q(path.relative(root, runDir))}`;
+}
+
+function writeUndoScript(runDir, root, moves, edits, platform = process.platform) {
+  if (platform === 'win32') {
+    const file = path.join(runDir, 'desfazer.cmd');
+    fs.writeFileSync(file, ['@echo off', `cd /d "${root}"`, undoCommand(root, runDir), ''].join('\r\n'));
+    return file;
+  }
   const lines = [
     '#!/usr/bin/env bash',
     `# Desfaz a arrumação de ${path.basename(runDir)}: restaura os arquivos editados e devolve os moves.`,
@@ -305,12 +406,14 @@ function applyMoves(root, moves, opts) {
   const config = lib.readConfig(root);
   const problems = validateMoves(root, moves);
   if (problems.length > 0) return { ok: false, code: 2, line: `Nada foi movido: ${problems.join('; ')}.` };
+  const testCommand = resolveTestCommand(root, opts);
+  if (testCommand.error) return { ok: false, code: 2, line: `Nada foi movido: ${testCommand.error}` };
 
   const runDir = path.join(archiveDir(root, config.layout), stamp());
   fs.mkdirSync(runDir, { recursive: true });
   writeManifest(path.join(runDir, 'manifesto.tsv'), moves);
 
-  const before = runTests(root, opts.testes);
+  const before = runTests(root, testCommand);
 
   // Referências: projeto inteiro + pastas extras (auto-memória, Cérebro).
   const extra = typeof opts.refs === 'string' ? opts.refs.split(',').map((d) => path.resolve(root, d.trim())) : [];
@@ -348,7 +451,7 @@ function applyMoves(root, moves, opts) {
     fs.renameSync(path.join(root, m.origem), to);
   }
   const undoFile = writeUndoScript(runDir, root, moves, edits);
-  const after = runTests(root, opts.testes);
+  const after = runTests(root, testCommand);
   const relRun = path.relative(root, runDir);
 
   if (before && after && before.ok && !after.ok && !opts.manter) {
@@ -365,7 +468,7 @@ function applyMoves(root, moves, opts) {
   return {
     ok: !after || after.ok || !before?.ok,
     code: 0,
-    line: `Movi ${moves.length} arquivo(s) e atualizei referências em ${edits.length}.${testes} Desfazer: ${path.relative(root, undoFile)}.`,
+    line: `Movi ${moves.length} arquivo(s) e atualizei referências em ${edits.length}.${testes} Desfazer: ${undoCommand(root, runDir)} (ou ${path.relative(root, undoFile)}).`,
   };
 }
 
@@ -415,4 +518,15 @@ if (require.main === module) {
   process.exit(result.code ?? (result.ok ? 0 : 1));
 }
 
-module.exports = { run, rewriteRefs, readManifest, planMoves, undo };
+module.exports = {
+  run,
+  splitArgv,
+  isAllowedTestArgv,
+  resolveTestCommand,
+  rewriteRefs,
+  readManifest,
+  planMoves,
+  undo,
+  writeUndoScript,
+  undoCommand,
+};

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);
   }