wizz-method 1.4.0 → 1.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 # Wizz Method
 
-**O método de agência orientado por IA, em português.** Um maestro lê seu pedido, descobre a área e chama o agente certo. Você fala normal, ele organiza o trabalho.
+**O método de agência orientado por IA, em português.** Um router lê seu pedido, descobre a área e chama o agente certo. Quando o trabalho cruza áreas, o Maestro organiza a sequência. Você fala normal, ele estrutura o trabalho.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.12.0-brightgreen)](https://nodejs.org)
@@ -10,7 +10,7 @@
 
 Cansado de reexplicar o contexto a cada conversa com a IA? O Wizz Method dá ao seu time uma estrutura fixa: agentes especializados (dev, design, copy, SEO, growth, ads, memória), linguagem fácil e resumida, e um encerramento padrão em toda resposta (**✅ o que fiz**, **➡️ próximo passo**, **🎯 comando**). Tudo em PT-BR, dentro do seu assistente de IA favorito.
 
-O ponto de entrada é um só. Invoque o `wizz-maestro`, mande o pedido, ele despacha para quem resolve.
+O ponto de entrada técnico é o `wizz-router`: ele faz a triagem e manda pedidos leves direto ao agente da área, ou chama o `wizz-maestro` quando precisa de orquestração.
 
 ## Os 7 agentes
 
@@ -32,6 +32,8 @@ A camada Wizz vale para todos os agentes: encerramento padrão (✅/➡️/🎯)
 
 **Pré-requisitos**: [Node.js](https://nodejs.org) v20.12+ · [Python](https://www.python.org) 3.10+ · [uv](https://docs.astral.sh/uv/)
 
+**Plataformas suportadas**: macOS, Linux e WSL (Windows Subsystem for Linux). Windows nativo (cmd.exe/PowerShell sem WSL) não é suportado — algumas CLIs opcionais do registry (`claude-video`, `voicebox`, `distribb`, `arcads`) usam checks POSIX (`test -d`, `$HOME`) e o installer as filtra fora dessa plataforma em vez de oferecer algo que nunca vai detectar como instalado.
+
 Instale o método no seu projeto:
 
 ```bash
@@ -46,7 +48,7 @@ Em seguida, rode a personalização Wizz. Ela pergunta o idioma de comunicação
 node <caminho-do-wizz-method>/src/modules/wizz/scripts/wizz-init.mjs .
 ```
 
-Por fim, invoque o `wizz-maestro` e mande seu pedido.
+Por fim, invoque o `wizz-router` e mande seu pedido. Se preferir começar simples, chamar o `wizz-maestro` também funciona para trabalhos multi-área, mas o router é a entrada canônica.
 
 **Instalação não-interativa** (para CI/CD):
 
@@ -59,7 +61,7 @@ Sem TTY, o idioma padrão é "Português (BR)". Use `--lang` ou a variável `WIZ
 
 ## Origem
 
-O Wizz Method é um fork independente do [Wizz Method](https://github.com/bmad-code-org/WIZZ-METHOD), mantido pela Wizz! comms. O motor continua o WIZZ: workflows, agentes de dev e produto e a arquitetura de skills. A camada Wizz adiciona marca, idioma, roteamento e os 7 agentes de agência por cima desse motor. Crédito e agradecimento ao projeto original.
+O Wizz Method é um fork independente do [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD), mantido pela Wizz! comms. O motor continua o BMAD: workflows, agentes de dev e produto e a arquitetura de skills. A camada Wizz adiciona marca, idioma, roteamento e os 7 agentes de agência por cima desse motor. Crédito e agradecimento ao projeto original.
 
 ## Documentação
 
@@ -69,4 +71,4 @@ O Wizz Method é um fork independente do [Wizz Method](https://github.com/bmad-c
 
 Licença MIT, veja [LICENSE](LICENSE) para detalhes.
 
-**Wizz** e **WIZZ-METHOD** são marcas da BMad Code, LLC. **Wizz Method** é marca própria da Wizz! comms. A licença MIT cobre apenas o código. Veja [TRADEMARK.md](TRADEMARK.md).
+**BMad** e **BMAD-METHOD** são marcas da BMad Code, LLC. **Wizz Method** é marca própria da Wizz! comms. A licença MIT cobre apenas o código. Veja [TRADEMARK.md](TRADEMARK.md).

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "wizz-method",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Wizz Method — método de agência orientado por IA em PT-BR (fork independente do BMad Method)",
   "keywords": [
     "agile",
@@ -25,6 +25,21 @@
     "wizz": "tools/installer/wizz-cli.js",
     "wizz-method": "tools/installer/wizz-cli.js"
   },
+  "files": [
+    "tools/installer",
+    "src/bmm-skills",
+    "src/core-skills",
+    "src/modules",
+    "src/scripts",
+    "src/skills-lib",
+    "!src/skills-lib/huashu-design/assets/**/*.mp3",
+    "!src/skills-lib/canvas-design/canvas-fonts/**/*.ttf",
+    "web-bundles",
+    "skills-registry.yaml",
+    "wizz-modules.yaml",
+    "removals.txt",
+    "tools/fetch-assets.mjs"
+  ],
   "scripts": {
     "docs:build": "node tools/build-docs.mjs",
     "docs:dev": "astro dev --root website",
@@ -32,6 +47,8 @@
     "docs:preview": "astro preview --root website",
     "docs:validate-links": "node tools/validate-doc-links.js",
     "docs:validate-sidebar": "node tools/validate-sidebar-order.js",
+    "eval:routing": "node evals/routing/run-routing-eval.mjs",
+    "eval:routing:llm": "node evals/routing/run-routing-eval.mjs --llm",
     "format:check": "prettier --check \"**/*.{js,cjs,mjs,json,yaml}\"",
     "format:fix": "prettier --write \"**/*.{js,cjs,mjs,json,yaml}\"",
     "format:fix:staged": "prettier --write",
@@ -40,17 +57,38 @@
     "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
     "lint:md": "markdownlint-cli2 \"**/*.md\"",
     "prepare": "command -v husky >/dev/null 2>&1 && husky || exit 0",
-    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run docs:build && npm run test:install && npm run test:urls && npm run validate:refs && npm run validate:skills && npm run docs:validate-sidebar",
+    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run docs:build && npm run test:install && npm run test:urls && npm run validate:refs && npm run validate:method-refs && npm run validate:skills && npm run docs:validate-sidebar",
     "rebundle": "node tools/installer/bundlers/bundle-web.js rebundle",
-    "test": "npm run test:refs && npm run test:install && npm run test:urls && npm run test:channels && npm run test:mcp && npm run test:cli && npm run test:deps && npm run lint && npm run lint:md && npm run format:check",
+    "sync:check": "node tools/sync-check.mjs",
+    "sync:global": "node tools/sync-global.mjs",
+    "test": "npm run test:refs && npm run test:install && npm run test:urls && npm run test:channels && npm run test:mcp && npm run test:env-vars && npm run test:cli && npm run test:deps && npm run test:dispatch-rule && npm run test:hooks && npm run test:quickupdate && npm run test:registry-schema && npm run test:method-refs-allowlist && npm run test:rtk-hook && npm run test:network-retry && npm run test:sync-check && npm run test:resolver && npm run test:fetch-assets && npm run test:install-smoke && npm run test:trace-report && npm run test:rehype-plugins && npm run test:workflow-path-regex && npm run test:preflight-tools-check && npm run lint && npm run lint:md && npm run format:check && npm run sync:check",
     "test:channels": "node test/test-installer-channels.js",
     "test:cli": "node test/test-cli-config.js",
     "test:deps": "node test/test-deps-cache.js",
+    "test:dispatch-rule": "node test/test-dispatch-rule-consistency.js",
+    "test:env-vars": "node test/test-env-vars.js",
+    "test:fetch-assets": "node test/test-fetch-assets.js",
+    "test:hooks": "node test/test-router-hook.js",
     "test:install": "node test/test-installation-components.js",
+    "test:install-smoke": "node test/test-install-smoke.js",
+    "test:install-smoke-mcp": "node test/test-install-smoke-mcp.js",
     "test:mcp": "node test/test-mcp-config.js",
+    "test:method-refs-allowlist": "node test/test-method-refs-allowlist.js",
+    "test:network-retry": "node test/test-network-retry.js",
+    "test:preflight-tools-check": "node test/test-preflight-tools-check.js",
+    "test:quickupdate": "node test/test-quick-update-gate.js",
     "test:refs": "node test/test-file-refs-csv.js",
+    "test:registry-schema": "node test/test-registry-schema.js",
+    "test:rehype-plugins": "node test/test-rehype-plugins.mjs",
+    "test:resolver": "node test/test-resolve-customization.js",
+    "test:rtk-hook": "node test/test-rtk-hook.js",
+    "test:sync-check": "node test/test-sync-check.js",
+    "test:trace-report": "node test/test-trace-report.js",
     "test:urls": "node test/test-parse-source-urls.js",
+    "test:workflow-path-regex": "node test/test-workflow-path-regex.js",
+    "validate:method-refs": "node tools/validate-method-refs.js --strict",
     "validate:refs": "node tools/validate-file-refs.js --strict",
+    "validate:registry-schema": "node tools/validate-registry-schema.js --strict",
     "validate:skills": "node tools/validate-skills.js --strict",
     "wizz:install": "node tools/installer/wizz-cli.js install",
     "wizz:uninstall": "node tools/installer/wizz-cli.js uninstall"
@@ -71,6 +109,12 @@
       "markdownlint-cli2"
     ]
   },
+  "overrides": {
+    "markdownlint-cli2": {
+      "js-yaml": "^4.3.0",
+      "markdown-it": "^14.2.0"
+    }
+  },
   "dependencies": {
     "@clack/core": "^1.3.1",
     "@clack/prompts": "^1.4.0",
@@ -80,7 +124,7 @@
     "csv-parse": "^6.1.0",
     "glob": "^11.0.3",
     "ignore": "^7.0.5",
-    "js-yaml": "^4.1.0",
+    "js-yaml": "^4.3.0",
     "picocolors": "^1.1.1",
     "semver": "^7.6.3",
     "xml2js": "^0.6.2",

package/skills-registry.yaml

@@ -27,6 +27,15 @@
 # 1. ESCOPO: sempre validar o escopo antes de instalar. PREFERIR local por projeto
 #    (.claude/skills do projeto). NÃO instalar em cloud global geral por padrão.
 #    Global do projeto apenas quando necessário. Nunca assumir global como padrão.
+#    EXCEÇÃO documentada: `wizz-router` (utility, id acima em `utility:`) é o
+#    único caso onde global é o padrão operacionalmente correto — sua função é
+#    ser o roteador flat que funciona mesmo FORA de um projeto Wizz (`when`:
+#    "descobre skills quando não se sabe a área"). Ele é sincronizado junto do
+#    hook global `wizz-router-enforce.js` via `npm run sync:global`
+#    (tools/sync-global.mjs só resincroniza skills que já existem em
+#    ~/.claude/skills — não instala novas; a instalação global inicial é
+#    escolha explícita do usuário via `npx skills add`/installer com escopo
+#    global). Todas as outras skills seguem a regra 1 normalmente (local).
 # 2. AUTO-DETECÇÃO DE DEPENDÊNCIAS (NPX/CLI/MCP): se a skill tem dependências,
 #    detectar automaticamente e instalar junto no momento do install da skill,
 #    cachear no projeto e reutilizar nas execuções futuras. Evitar re-instalação a
@@ -61,63 +70,124 @@ areas:
   designer:
     agent: wizz-designer
     summary: "Design de produto e UI: interfaces, landing pages, design systems, motion, 3D."
+    # 3 PORTAS DE ENTRADA (2026-07, consolidação leve): o agente OFERECE/INVOCA
+    # apenas as skills com `entry: true`. As demais são puxadas PELA porta da sua
+    # camada (campo `door`) ou por pedido explícito do usuário — nunca oferecidas
+    # soltas. Nada foi fundido: todos os arquivos e references continuam intactos.
     skills:
+      # ── Porta 1: DIREÇÃO (decidir antes de construir) ──
+      - id: decision-maker
+        entry: true
+        door: direcao
+        when: "PORTA de direção: todo trabalho de decidir ANTES de construir. Brief visual inicial (6 decisões de estética + 3 lógicas) no kickoff. Puxa: taste-skill (direção anti-slop de brief novo) e motion-3d-director (decidir caminho motion/3D/vídeo)."
+      - id: taste-skill
+        door: direcao
+        when: "Anti-slop em briefs NOVOS: lê o brief, define a direção e audita contra defaults de AI."
+      - id: motion-3d-director
+        door: direcao
+        when: "Direção de motion/animação, 3D, WebGL, scroll cinematográfico, image-to-video. Decide o caminho ANTES de implementar."
+
+      # ── Porta 2: CONSTRUÇÃO E POLISH DE UI ──
       - id: ui-ux-pro-max
-        when: "Design system, paleta, tipografia, componente; pedido de UI amplo. Principal de busca de padrões/estilos."
-      - id: impeccable
-        when: "Gate de polish/qualidade de frontend: hardening de UI, acessibilidade, anti-padrões. Refina o que já existe."
-      - id: huashu-design
-        when: "Direção visual + protótipo HTML hi-fi, exploração de variantes, review 5-dim, export MP4/GIF."
+        entry: true
+        door: construcao
+        when: "PORTA de construção: criar/melhorar UI (design system, paleta, tipografia, componente, página). Puxa: premium-landing-ui-researcher (landing premium greenfield), ui-component-curator (1 componente em projeto existente), impeccable (gate de polish/acessibilidade), taste-redesign (anti-slop em código existente), huashu-design (protótipo HTML hi-fi/variantes/review) e react-components (Stitch→React)."
       - id: premium-landing-ui-researcher
+        door: construcao
         when: "Projeto NOVO (greenfield): cria landing premium do zero, hero, 3D high-end. Estratégia source-first."
       - id: ui-component-curator
+        door: construcao
         when: "Projeto EXISTENTE: qual componente/efeito adicionar que combina com o estilo atual."
-      - id: motion-3d-director
-        when: "Direção de motion/animação, 3D, WebGL, scroll cinematográfico, image-to-video."
-      - id: remotion-best-practices
-        when: "Vídeo programático em React (Remotion) especificamente."
+      - id: impeccable
+        door: construcao
+        when: "Gate de polish/qualidade de frontend: hardening de UI, acessibilidade, anti-padrões. Refina o que já existe."
+      - id: taste-redesign
+        door: construcao
+        when: "Anti-slop em projeto EXISTENTE: audita o código atual, lista problemas, prioriza fixes."
+      - id: huashu-design
+        door: construcao
+        when: "Direção visual + protótipo HTML hi-fi, exploração de variantes, review 5-dim, export MP4/GIF."
+      - id: react-components
+        door: construcao
+        when: "Converter design (Stitch MCP) em componentes React/Vite."
+
+      # ── Porta 3: MOTION E ASSETS (executar animação e gerar mídia) ──
       - id: animate
-        when: "Craft de animação/micro-interação: regras do Emil Kowalski (saída > entrada, só transform/opacity, respeitar reduced-motion). Complementa o motion-3d-director com a execução fina. Traz references + exemplos .tsx."
+        entry: true
+        door: motion
+        when: "PORTA de motion/assets: executar animação e gerar mídia. Craft de micro-interação (regras do Emil Kowalski: saída > entrada, só transform/opacity, reduced-motion). Puxa: design-motion-principles (auditar animação existente), remotion-best-practices (vídeo em React), canvas-design (PNG/PDF por código) e algorithmic-art (visual generativo)."
       - id: design-motion-principles
+        door: motion
         when: "Auditor de movimento: revisa animação existente e aponta scale(0) no início, easing cru, reduced-motion faltando; pesa contenção/polimento/diversão pelo contexto."
+      - id: remotion-best-practices
+        door: motion
+        when: "Vídeo programático em React (Remotion) especificamente."
       - id: canvas-design
+        door: motion
         when: "Gerar PNG/PDF editável por código (carrossel, quote card, infográfico) com fonte/cor/logo sempre certos. Traz canvas-fonts."
       - id: algorithmic-art
+        door: motion
         when: "Visual generativo por código (flow fields, ruído, partículas) para fundo/textura de hero, único a cada render, sem cara de banco de imagem."
-      - id: taste-skill
-        when: "Anti-slop em briefs NOVOS: lê o brief, define a direção e audita contra defaults de AI."
-      - id: taste-redesign
-        when: "Anti-slop em projeto EXISTENTE: audita o código atual, lista problemas, prioriza fixes."
-      - id: react-components
-        when: "Converter design (Stitch MCP) em componentes React/Vite."
-      - id: decision-maker
-        when: "Brief visual inicial: força 6 decisões de estética + 3 lógicas. Entra no kickoff, antes de construir."
     mcps:
       - id: magic
         when: "Gerar/refinar componentes prontos via 21st.dev (UI builder, inspiration, refiner)."
         server:
           command: npx
-          args: ["-y", "@21st-dev/magic"]
+          # Pin de supply chain (2026-07-06): versão fixa; atualizar conscientemente.
+          args: ["-y", "@21st-dev/magic@0.1.0"]
           env:
             API_KEY: "${MAGIC_API_KEY}"
     clis:
       - id: hyperframes
         when: "Renderizar vídeo a partir de HTML/CSS/animação (HTML→MP4, agent-native, 20+ skills). Alternativa HTML-nativa ao Remotion (que é React). Precisa ffmpeg + Node 22 + Chrome headless."
+        # Sem `platform:` deliberadamente (M20/2026-07-07): `check`/`install`
+        # são via npx (Node), não POSIX puro (sem `test -d`/`$HOME`/`grep`);
+        # gatear por plataforma esconderia a CLI de quem tem Node no Windows
+        # nativo sem necessidade. O runtime real (ffmpeg + Chrome headless)
+        # ainda pode faltar lá, mas isso é o mesmo tipo de gap que `verify:`
+        # cobre nas clone-and-run abaixo, não falta de suporte de plataforma.
         check: "npx --yes hyperframes --version"
-        install: "npx skills add heygen-com/hyperframes"
+        # Pin de supply chain (2026-07-07): SHA fixo via fragmento de URL git
+        # (a CLI `skills add` não suporta um flag --pin/@ref próprio; "Any git
+        # URL" é fonte suportada, então usamos a convenção #<sha> de URL git);
+        # atualizar conscientemente. Antes: `npx skills add heygen-com/hyperframes`
+        # (HEAD sem pin, A8/RT2).
+        install: "npx skills add https://github.com/heygen-com/hyperframes.git#4c8064d4d3d1ffe51a10b1c7eee79a49b2fc468f"
       - id: claude-video
         when: "Analisar/entender vídeo EXISTENTE: baixa, extrai frames e transcreve para resumir, achar momentos ou diagnosticar footage. NÃO cria vídeo. Precisa ffmpeg + yt-dlp (+ Groq/OpenAI p/ transcrição sem legenda)."
+        # M20 (2026-07-07): check é POSIX puro (`test -d`, `$HOME`); em
+        # Windows nativo sempre falha e o usuário é convidado a reinstalar
+        # algo que nunca vai "ficar instalado" ali. Suporte oficial é
+        # macOS/Linux/WSL (WSL reporta platform 'linux').
+        platform: [darwin, linux]
         check: "test -d $HOME/.claude/skills/watch"
-        install: "npx skills add bradautomates/claude-video"
+        # Pin de supply chain (2026-07-07): SHA fixo via fragmento de URL git
+        # (mesma convenção do hyperframes acima); atualizar conscientemente.
+        # Antes: `npx skills add bradautomates/claude-video` (HEAD sem pin, A8/RT2).
+        install: "npx skills add https://github.com/bradautomates/claude-video.git#83da59fa78c3eee9e20f515fe75c438bb5166efd"
       - id: buttercut
         when: "EDITAR vídeo por IA: cortes, selects, cenas, roughcut via XML/FFmpeg. Sugerir quando o pedido for editar/cortar vídeo. Clone-and-run no PROJETO (não é skill add), pesado: Ruby + Python + FFmpeg + WhisperX. AVISOS: ~GB de modelos (WhisperX), build demorado, só Apple Silicon."
         platform: darwin-arm64
         check: "test -d ./buttercut"
-        install: "git clone https://github.com/barefootford/buttercut.git"
+        # Pin de supply chain (2026-07-06): checkout de SHA fixo; atualizar conscientemente.
+        install: "git clone https://github.com/barefootford/buttercut.git buttercut && git -C buttercut checkout 1383f964ebc8b43c4af17f70b3ec6f611b18b3ce"
+        # M14: `check` só prova "o clone existe"; o runtime pesado (Ruby +
+        # Python + FFmpeg + WhisperX, documentado no `when` acima) não é
+        # testado por ele. `verify` cobre a dependência mínima (falha =
+        # aviso, nunca abort — CLI clone-and-run continua opt-in).
+        verify: "command -v ffmpeg >/dev/null 2>&1 && command -v ruby >/dev/null 2>&1 && command -v python3 >/dev/null 2>&1"
       - id: voicebox
         when: "Voz/TTS/clonagem de voz local para narração/VO de vídeo (7 engines TTS + Whisper STT). App desktop que expõe endpoint MCP local em runtime. Clone-and-run no projeto."
+        # M20: check é POSIX puro (`test -d`); suporte oficial macOS/Linux/WSL.
+        platform: [darwin, linux]
         check: "test -d ./voicebox"
-        install: "git clone https://github.com/jamiepine/voicebox.git"
+        # Pin de supply chain (2026-07-06): checkout de SHA fixo; atualizar conscientemente.
+        install: "git clone https://github.com/jamiepine/voicebox.git voicebox && git -C voicebox checkout f2cf2a729d733acd7c759d85c6ace2d602f50d6e"
+        # Sem `verify:` deliberadamente (2026-07-07): diferente de
+        # buttercut/arcads, o `when` acima não documenta uma dependência de
+        # sistema específica (é um app desktop autocontido que expõe um
+        # endpoint MCP local) — nada de concreto pra checar sem inventar um
+        # requisito que o registry não afirma.
     references:
       - "references/premium-agency-rules.md (regras $150k-tier, importadas por impeccable/huashu no modo high-end)"
 
@@ -155,8 +225,15 @@ areas:
     clis:
       - id: distribb
         when: "EXECUTAR distribuição de SEO: publicar artigos + construir backlinks pela rede da Distribb, conectar Google Search Console, autopublicar notícias. Complementa (não duplica) as skills de SEO que só geram/auditam. Requer Distribb API + GSC (+ DataForSEO/Ahrefs no plano free)."
+        # M20: check é POSIX puro (`ls`, `grep -qi`, `$HOME`); suporte oficial
+        # macOS/Linux/WSL.
+        platform: [darwin, linux]
         check: "ls $HOME/.claude/skills 2>/dev/null | grep -qi distribb"
-        install: "npx skills add Bomx/distribb-skill"
+        # Pin de supply chain (2026-07-07): SHA fixo via fragmento de URL git
+        # (mesma convenção do hyperframes/claude-video acima); atualizar
+        # conscientemente. Antes: `npx skills add Bomx/distribb-skill` (HEAD
+        # sem pin, A8/RT2).
+        install: "npx skills add https://github.com/Bomx/distribb-skill.git#860700de171f2ff741985ffdc739010f3f0c0e25"
 
   growth:
     agent: wizz-growth
@@ -212,7 +289,8 @@ areas:
         # before writing; if verify fails the server is skipped, not written.
         setup:
           bin: scrapling
-          install: 'uv tool install "scrapling[ai]" || pipx install "scrapling[ai]" || pip install --user "scrapling[ai]"'
+          # Pin de supply chain (2026-07-06): versão fixa; atualizar conscientemente.
+          install: 'uv tool install "scrapling[ai]==0.4.10" || pipx install "scrapling[ai]==0.4.10" || pip install --user "scrapling[ai]==0.4.10"'
           post_install: "{bin} install"
           verify: "{bin} --version"
 
@@ -253,14 +331,29 @@ areas:
         when: "Gestão real de campanha Meta/Facebook/Instagram via API (criar/editar/medir ads)."
         server:
           command: npx
-          args: ["-y", "mcp-meta-ads"]
+          # Pin de supply chain (2026-07-06): versão fixa; atualizar conscientemente.
+          # Risco (2026-07-07, C5/RT3): pacote COMUNITÁRIO (não é @meta/@facebook
+          # oficial), revisado nesta data na versão pinada 1.0.0; acesso a
+          # META_ACCESS_TOKEN = gasto real de ads. O mesmo token é reaproveitado
+          # pela CLI `arcads` (ver clis.arcads nesta mesma área): duas
+          # ferramentas, mesma credencial. Recomendado: token com escopo
+          # mínimo (ads_read pra relatórios; ads_management só com campanha
+          # real confirmada).
+          args: ["-y", "mcp-meta-ads@1.0.0"]
           env:
             META_ACCESS_TOKEN: "${META_ACCESS_TOKEN}"
     clis:
       - id: arcads
         when: "GERAR vídeo-ad e imagem por IA (Seedance/Sora/Veo/Kling/OmniHuman + Nano Banana) e publicar como Meta ad. Clone-and-run no projeto: git clone + ./scripts/setup.sh; precisa Python 3.10+ e ARCADS API key em .env (META_ACCESS_TOKEN opcional p/ publicar)."
+        # M20: check é POSIX puro (`test -d`); suporte oficial macOS/Linux/WSL.
+        platform: [darwin, linux]
         check: "test -d ./arcads-claude-code"
-        install: "git clone https://github.com/krusemediallc/arcads-claude-code.git"
+        # Pin de supply chain (2026-07-06): checkout de SHA fixo; atualizar conscientemente.
+        install: "git clone https://github.com/krusemediallc/arcads-claude-code.git arcads-claude-code && git -C arcads-claude-code checkout 0b0d3610bbdcfcc2607c77a748d6abb341adda46"
+        # M14: `check` só prova "o clone existe", não o runtime (Python 3.10+
+        # documentado no `when` acima). `verify` cobre essa dependência mínima
+        # (falha = aviso, nunca abort — CLI clone-and-run continua opt-in).
+        verify: "command -v python3 >/dev/null 2>&1 && python3 -c 'import sys; sys.exit(0 if sys.version_info >= (3, 10) else 1)'"
 
   architect:
     agent: wizz-agent-architect
@@ -288,10 +381,18 @@ areas:
         when: "Construir/melhorar um agente ou produto de IA: escrever/revisar system prompt, definir persona/tom, guardrails e recusas, few-shot, chain-of-thought, orquestração multi-agente, handoff, detecção de frustração, generative UI, avaliar qualidade de saída. Base para desenhar os próprios agentes do método. 44 padrões (Owl-Listener, MIT)."
     mcps:
       - id: supabase
-        when: "Operar Supabase de verdade: rodar SQL, migrations, inspecionar schema/RLS, logs."
+        when: "Operar Supabase de verdade: rodar SQL, migrations, inspecionar schema/RLS, logs. Default é READ-ONLY e escopado a um projeto (--read-only --project-id); para ESCREVER (migrations, mutações), o agente precisa remover conscientemente o --read-only desta entrada antes de usar — nunca por padrão silencioso."
         server:
           command: npx
-          args: ["-y", "@supabase/mcp-server-supabase@latest"]
+          # Pin de supply chain (2026-07-06): versão fixa (era @latest); atualizar conscientemente.
+          # Read-only + projeto escopado por padrão (2026-07-07, C5/RT3):
+          # SUPABASE_ACCESS_TOKEN sem esses flags permite SQL arbitrário na
+          # conta inteira. --read-only roda como usuário Postgres somente
+          # leitura e desliga tools de mutação (projeto/branch/storage);
+          # --project-id escopa ao projeto em SUPABASE_PROJECT_REF. Escrita
+          # continua a 1 edição de distância (remover --read-only), nunca o
+          # default.
+          args: ["-y", "@supabase/mcp-server-supabase@0.8.2", "--read-only", "--project-id", "${SUPABASE_PROJECT_REF}"]
           env:
             SUPABASE_ACCESS_TOKEN: "${SUPABASE_ACCESS_TOKEN}"
 
@@ -300,7 +401,7 @@ areas:
     summary: "QA: verificar o código de fora (testes, E2E, review adversarial)."
     skills:
       - id: adversarial-reviewer
-        when: "Caçar bugs adversarialmente, stress-test de PR, 'tear this apart'. (Global; o engine usa wizz-review-adversarial-general por dentro.)"
+        when: "Passe único adversarial, ad hoc, fora de workflow — 'tear this apart' num trecho colado, sem contexto de projeto. Não confundir com wizz-review-adversarial-general (camada interna 'Blind Hunter' chamada só por wizz-code-review) nem com wizz-code-review (orquestrador bmm: 3 camadas paralelas + triagem, para review real de diff/PR)."
       - id: agent-browser
         when: "Verificação visual/browser, preencher forms, screenshots, testar UI no navegador. CLI já instalado (não é MCP); browser SEMPRE via agent-browser, nunca Playwright."
     # qa NÃO declara mcps: verificação de browser é via agent-browser (CLI/skill),
@@ -309,7 +410,8 @@ areas:
       - id: agent-browser
         when: "Dirigir um browser real pra E2E/verificação: navegar, clicar, preencher form, screenshot, console. É CLI, não MCP."
         check: "agent-browser --version"
-        install: "npm install -g agent-browser"
+        # Pin de supply chain (2026-07-06): versão fixa; atualizar conscientemente.
+        install: "npm install -g agent-browser@0.27.0"
 
   analyst:
     agent: wizz-agent-analyst
@@ -324,7 +426,8 @@ areas:
         when: "Pesquisa web/prior-art durante planejamento (web search, descoberta de fontes)."
         server:
           command: npx
-          args: ["-y", "exa-mcp-server"]
+          # Pin de supply chain (2026-07-06): versão fixa; atualizar conscientemente.
+          args: ["-y", "exa-mcp-server@3.2.1"]
           env:
             EXA_API_KEY: "${EXA_API_KEY}"
 
@@ -356,19 +459,48 @@ mcp_utility:
     when: "Docs atualizadas de qualquer lib/framework/SDK (React, Next, Prisma, Tailwind...). Útil em todo dev."
     server:
       command: npx
-      args: ["-y", "@upstash/context7-mcp"]
+      # Pin de supply chain (2026-07-06): versão fixa; atualizar conscientemente.
+      args: ["-y", "@upstash/context7-mcp@3.2.2"]
 
 # ─────────────────────────────────────────────────────────────────────────────
 # CLIs — ferramentas de linha de comando que os agentes chamam direto (não são
 # MCP nem skill). O installer DETECTA se já estão instaladas (check) e, por
 # padrão, só RECOMENDA o comando de install; instala de verdade apenas se o
 # usuário marcar. `clis:` por área; `cli_utility:` para as cross-cutting.
+#
+# Campos opcionais por entrada (fase 2 da auditoria, M27/M14):
+#   min_version — pin mínimo comparado via semver pelo installer (detectClis);
+#                 abaixo do pin, a entrada some de `installed: true` e volta
+#                 como upgrade oferecido (mensagem "atualizando X A → B"). A
+#                 divisão de responsabilidade é deliberada: `check` só prova
+#                 presença/versão (roda o comando e devolve texto com o
+#                 número), a COMPARAÇÃO em si vive no installer (JS), não em
+#                 shell embutido — mais fácil de testar e de ler.
+#   verify       — probe pós-check/pós-install de dependência mínima (ex.:
+#                 `command -v ffmpeg`), útil pras CLIs clone-and-run onde
+#                 `check` só prova "o clone existe", não que o runtime real
+#                 funciona. Falha em `verify` nunca aborta (filosofia CLI
+#                 opt-in) — só rebaixa `installed` e avisa.
 # ─────────────────────────────────────────────────────────────────────────────
 cli_utility:
   - id: rtk
     when: "Token economy: proxy que corta 60-90% de tokens em comandos de dev. O wizz-router assume RTK ativo (Passo 0). Útil em todo o ecossistema."
+    # min_version formal (2026-07-07, M27) substitui o sort -V embutido no
+    # shell que existia aqui antes: auditoria 2026-07-07 (C4/RT1) achou 0.30.1
+    # instalado vs v0.43.0 pinado, invisível ao check anterior a ele (`rtk
+    # --version` só testava que rodava). Agora `check` volta a ser só
+    # presença/versão (roda e imprime o número); a COMPARAÇÃO semver contra
+    # min_version é feita pelo installer (detectClis), não em shell.
+    min_version: 0.43.0
     check: "rtk --version"
-    install: "curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh"
+    # Pin de supply chain (2026-07-07): tag v0.43.0 (antes: branch master)
+    # Checksum do install.sh nesta tag (2026-07-07): sha256
+    # d6eb73a772903e13ff34ee1be8a8b24e896ba9a978f20d2279a08b4083ea6f77
+    # (RT1: tag git pode ser movida à força; o checksum trava o conteúdo real
+    # que será executado, não só o nome da tag. Verificado com `shasum -c`
+    # antes do `sh`; se a tag mudar de conteúdo, o install aborta em vez de
+    # rodar script desconhecido.)
+    install: "curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/tags/v0.43.0/install.sh -o /tmp/rtk-install-v0.43.0.sh && echo 'd6eb73a772903e13ff34ee1be8a8b24e896ba9a978f20d2279a08b4083ea6f77  /tmp/rtk-install-v0.43.0.sh' | shasum -a 256 -c - && sh /tmp/rtk-install-v0.43.0.sh"
 
 # ─────────────────────────────────────────────────────────────────────────────
 # SQUADS — painéis consultivos de personas (rodam via wizz-party-mode).

package/src/bmm-skills/4-implementation/wizz-code-review/SKILL.md

@@ -5,6 +5,8 @@ description: 'Review code changes adversarially using parallel review layers (Bl
 
 # Code Review Workflow
 
+> **Cross-reference:** this is the orchestrator — it gathers context, runs three parallel adversarial layers (Blind Hunter via `wizz-review-adversarial-general`, Edge Case Hunter, Acceptance Auditor), then triages and presents findings by severity. Use it for a real diff/PR review. For a quick single-pass adversarial read with no workflow overhead, use `adversarial-reviewer` directly instead.
+
 **Goal:** Review code changes adversarially using parallel review layers and structured triage.
 
 **Your Role:** You are an elite code reviewer. You gather context, launch parallel adversarial reviews, triage findings with precision, and present actionable results. No noise, no filler.

package/src/bmm-skills/4-implementation/wizz-quick-dev/SKILL.md

@@ -37,8 +37,11 @@ A specification should target a **single user-facing goal** within **900–1600
 
 You are the leaf: the maestro demotes here for pointed work (bug, tweak, single-goal feature). Re-check scope against the shared complexity signal (areas, steps, needs-planning?, artifact+memory?):
 
-- If clarification reveals the request is actually **multi-goal / multi-area** (2+ top-level shippable deliverables, or it spans several areas), do not silently absorb it. Surface it and propose escalating to `wizz-maestro` to orchestrate the sequence. Proceed solo only if the user confirms a narrowed single goal.
-- Stay solo for genuinely single-goal work, even when it crosses layers/files.
+**Dispatch rule:** IF 2+ areas → `wizz-maestro`, always. ELSE count the 3 remaining factors (multi-step, needs planning, produces a memorable artifact); 2+ factors → `wizz-maestro`.
+
+- If clarification reveals the request is actually **multi-goal / multi-area** (2+ top-level shippable deliverables, or it spans several areas), do not silently absorb it. That is clause 1: escalate regardless of how light each individual part looks. Surface it and propose escalating to `wizz-maestro` to orchestrate the sequence. Proceed solo only if the user confirms a narrowed single goal.
+- If it is genuinely single-area but hits 2+ of the remaining factors (multi-step, needs planning, produces a memorable artifact), also escalate. Do not silently absorb heavy single-area work either.
+- Stay solo only for single-area work with 0-1 of those factors, even when it crosses layers/files.
 
 ## Conventions
 

package/src/core-skills/_shared/handoff-protocol.md

@@ -0,0 +1,61 @@
+# Protocolo de Handoff Wizz (fonte única)
+
+Contrato mínimo que todo orquestrador ou spawn de subagente usa ao delegar
+trabalho: wizz-router, wizz-maestro, wizz-party-mode (subagent/agent-team)
+e swarm-orchestrator. Objetivo: cortar a dupla consulta ao cerebro (cerebro
+pago 2x na mesma cadeia), travar o loop router-maestro-router, e passar só
+a seção da skill que importa (progressive disclosure), não a skill inteira.
+
+## Campos do brief
+
+- origem: quem está delegando (ex: wizz-router, wizz-maestro). Regra
+  anti-loop: nunca invoque quem já está na cadeia de origem. Exemplo
+  proibido: router delega pro maestro, maestro devolve pro router.
+- cérebro já consultado: resumo de até 3 linhas do que o /cerebro ver já
+  trouxe (estado do projeto, decisões recentes relevantes à área). Se este
+  campo veio preenchido, quem recebe o handoff não roda /cerebro ver de
+  novo, usa o resumo recebido.
+- decisões já tomadas na cadeia: lista curta do que já foi decidido antes
+  deste handoff (ex: paleta aprovada, escopo definido).
+- seção relevante da skill: aponte o arquivo ou seção específica a
+  carregar, não a skill inteira (ex: paid-ads/references/budget.md). Quem
+  recebe carrega só isso, não o pacote completo da skill.
+- model_hint (opcional): sugestão de modelo. Trabalho braçal (execução
+  mecânica, correção pontual) sugere haiku ou sonnet; revisão, arquitetura
+  ou decisão sugere um modelo forte. Campo opcional: um handoff sem ele
+  funciona normal, não trava nada.
+
+## Exemplo de brief
+
+    origem: wizz-router
+    cérebro já consultado: projeto usa Next.js + Supabase; paleta copper
+      aprovada; falta terminar o checkout.
+    decisões já tomadas na cadeia: escopo é só mobile-first.
+    seção relevante da skill: page-cro/references/checkout-flow.md
+    model_hint: sonnet
+
+## Regra anti-loop
+
+Hoje a prevenção de loop é só instrucional (nada programático barra). Quem
+delega sempre declara `origem`; quem recebe nunca invoca de volta quem
+está na cadeia. Se precisar de mais triagem, resolve sozinho ou rebaixa
+para o agente de área, nunca devolve para quem chamou.
+
+## Quem usa este protocolo
+
+- wizz-router: declara ao delegar para o agente de área ou para o maestro.
+- wizz-maestro: declara ao delegar para os agentes de área.
+- wizz-party-mode (mode-subagent, mode-agent-team): inclui o resumo do
+  cerebro e as decisões da cadeia no brief de cada persona/subagente.
+- swarm-orchestrator: inclui o mesmo resumo no spawn prompt de cada
+  teammate (eles não herdam a conversa do lead).
+
+## Cobertura de eval
+
+O cenário de loop router-maestro-router não ganhou caso automatizado em
+evals/routing/dataset.json: o runner (run-routing-eval.mjs) testa a
+classificação de 1 prompt do usuário (isTrivial + rota via LLM), não
+simula uma cadeia de handoff nem lê um campo origem. Um caso com esse
+campo não seria exercido por nenhum código do runner hoje. A cobertura
+real da regra anti-loop fica instrucional (seção acima) até o runner
+ganhar suporte a cenário multi-hop.

package/src/core-skills/wizz-customize/SKILL.md

@@ -57,7 +57,7 @@ If a team or user override already exists, read it first and summarize what's al
 
 When ambiguous, present both with tradeoff, recommend one, let the user decide.
 
-Intent outside the exposed surface (step logic, ordering, anything not in `customize.toml`): say so; offer `activation_steps_prepend`/`append` or `persistent_facts` as approximations, or recommend `bmad-builder` to create a custom skill.
+Intent outside the exposed surface (step logic, ordering, anything not in `customize.toml`): say so; offer `activation_steps_prepend`/`append` or `persistent_facts` as approximations, or recommend the **Wizz Builder** module (`bmb`, see [Official Modules](https://docs.wizz-method.org/reference/modules/)) to create a custom skill.
 
 ## Step 4: Compose the override
 
@@ -107,5 +107,5 @@ Otherwise the skill isn't done — finish or tell the user they're exiting incom
 ## When this skill can't help
 
 - **Central config** (`{project-root}/_wizz/custom/config.toml`) — see the [How to Customize Wizz guide](https://docs.wizz-method.org/how-to/customize-wizz/).
-- **Step logic, ordering, behavior not in `customize.toml`** — open a feature request, or use `bmad-builder` to create a custom skill. Offer to help with either.
+- **Step logic, ordering, behavior not in `customize.toml`** — open a feature request, or use the **Wizz Builder** module (`bmb`) to create a custom skill. Offer to help with either.
 - **Skills without a `customize.toml`** — not customizable.

package/src/core-skills/wizz-party-mode/references/mode-agent-team.md

@@ -4,7 +4,7 @@ Active when `{workflow.party_mode}` resolves to `agent-team` (or a `--mode agent
 
 Your job shifts from weaving to hosting: kick off the topic, keep turns short and in character, pull the thread back when it wanders, and surface the exchange to the user. Voice, brevity, and clash still hold.
 
-In each member's standing brief, carry: their persona; the group's `scene` and any behavioral instructions in the persona as binding direction; their `model` if one is set (a session `--model` pin wins for everyone); and the instruction to check anything that could be stale since the model's training cutoff with web search rather than guessing.
+In each member's standing brief, carry: their persona; the group's `scene` and any behavioral instructions in the persona as binding direction; their `model` if one is set (a session `--model` pin wins for everyone); the instruction to check anything that could be stale since the model's training cutoff with web search rather than guessing; and, per the [shared handoff protocol](../../_shared/handoff-protocol.md), the cerebro 3-line summary plus the decisions already made in this chain, so members don't re-run their own cerebro lookup.
 
 ## Model choice
 

package/src/core-skills/wizz-party-mode/references/mode-subagent.md

@@ -4,7 +4,7 @@ Active when `{workflow.party_mode}` resolves to `subagent` (or a `--mode subagen
 
 ## Spawning
 
-Give each agent the objective, their persona, the context, and what the others said if they're reacting. For a custom member, hand them their `persona` as their character and fold their `capabilities` note into the brief; spawn them with their `model` if one is set (a session `--model` pin wins for everyone). Always carry two things into the brief: the group's `scene` and any behavioral instructions in the persona are binding direction, and anything that could be stale since the model's training cutoff should be checked with web search rather than guessed.
+Give each agent the objective, their persona, the context, and what the others said if they're reacting. Follow the [shared handoff protocol](../../_shared/handoff-protocol.md): fold in the cerebro 3-line summary and the decisions already made in this chain, so the subagent doesn't re-run its own cerebro lookup. For a custom member, hand them their `persona` as their character and fold their `capabilities` note into the brief; spawn them with their `model` if one is set (a session `--model` pin wins for everyone). Always carry two things into the brief: the group's `scene` and any behavioral instructions in the persona are binding direction, and anything that could be stale since the model's training cutoff should be checked with web search rather than guessed.
 
 Trust their *thinking*: let them decide what to read and how to reach a view; don't script their substance with do-and-don't checklists — that's what produces lifeless blobs. But hold the *form*: a length cap (usually a sentence or three) and the instruction to react to what was just said rather than file a report. Constraining length and stance protects the conversation; constraining their reasoning kills it. Stay in character throughout; a persona goes long only when the user asked it to dig in.
 

package/src/core-skills/wizz-review-adversarial-general/SKILL.md

@@ -5,6 +5,8 @@ description: 'Perform a Cynical Review and produce a findings report. Use when t
 
 # Adversarial Review (General)
 
+> **Cross-reference:** this is the internal "Blind Hunter" layer that `wizz-code-review` invokes as one of three parallel reviewers (diff only, no project context, no triage). It is not meant to be invoked standalone by a user. For an ad hoc adversarial pass outside a bmm workflow, use the `adversarial-reviewer` skill directly; for the full triaged multi-layer review of a real diff, run `wizz-code-review`.
+
 **Goal:** Cynically review content and produce findings.
 
 **Your Role:** You are a cynical, jaded reviewer with zero patience for sloppy work. The content was submitted by a clueless weasel and you expect to find problems. Be skeptical of everything. Look for what's missing, not just what's wrong. Use a precise, professional tone — no profanity or personal attacks.