wizz-method 2.14.0 → 2.16.0

package/src/skills-lib/wizz-ui-component-curator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wizz-ui-component-curator
-description: analyze an existing frontend project, infer its visual style and product tone, then research and recommend compatible UI components and effects from public component catalogs, registries and source repositories. use when the user wants help choosing components, effects, sections, or visual patterns that fit an existing project — especially hero effects, cards, buttons, testimonials, pricing sections, navigation, or any interactive pattern. trigger whenever the user wants to add a UI element and wants Claude to study the project first before suggesting options. always inspect the codebase and exact component sources, provide evidence and plan before editing.
+description: analyze an existing frontend project, infer its visual style and product tone, then research and recommend compatible UI components and effects from public component catalogs, registries and source repositories. use when the user wants help choosing components, effects, sections, or visual patterns that fit an existing project or dashboard — especially hero effects, cards, buttons, hovers, loading animations, testimonials, pricing sections, navigation, or any interactive pattern. trigger whenever the user wants to add a UI element and wants Claude to study the project first before suggesting options. always inspect the codebase and exact component sources, provide evidence and plan before editing.
 ---
 
 # Overview
@@ -19,6 +19,8 @@ Act as a UI curator with taste and restraint — not a gallery explorer. Optimiz
 
 If `{output_folder}/design-state.yaml` exists, the need being worked is already written there: take its `query`, `budget.fontes` and `floor` instead of improvising them, honour the `proibidos` block, and write the result back under `discoveries` with the `need` id. If the request does not match any open need, say so before researching: an unplanned need is either a gap in the map (go back to `wizz-design-needs`) or scope creep.
 
+Not there? Look before deciding it does not exist: `find . -name design-state.yaml -not -path '*/node_modules/*'`. A map found anywhere else is still the map: use it, and tell the user it is off-place (it belongs in `{output_folder}`).
+
 With no state file, continue normally.
 
 ## 1. Read and infer the style DNA
@@ -38,7 +40,9 @@ Do not ask the user to describe the style unless the project has no inspectable
 
 ## 2. Search and inspect public sources
 
-Start with existing project components. Then search appropriate public sources: [React Bits](https://reactbits.dev/), [Cult UI](https://www.cult-ui.com/docs), [Componentry](https://componentry.dev/), or [shadcn/ui](https://ui.shadcn.com/docs). Compare at least two suitable sources when available.
+Start with existing project components. Then search the public sources. The full authorized list (React Bits, Cult UI, Ali Imam, Watermelon, StyleUI, Skiper UI, Bklit UI, Componentry, shadcn/ui, plus the reference galleries) lives in one place: [component-sources](../wizz-premium-landing-ui-researcher/references/component-sources.md). Read it instead of relying on memory. Compare at least two suitable sources per need.
+
+Use whatever search tools the session has: web search (Exa when configured, WebSearch otherwise), WebFetch, scrapling, and `agent-browser` to watch hover and motion live. A tool that errors or hangs is not the end of the research: record the failure, move to the next tool, and never stop without reporting what was and was not checked.
 
 Open the exact demo and source file/registry item. Check the actual imports, license, dependencies, stack variant and revision; use current official documentation (Context7 when available) for API compatibility. Inspect animation/interaction in the available browser; label static-only inspection honestly. If a source fails, record the failure and continue elsewhere.
 
@@ -68,6 +72,22 @@ Send the exact candidate links and recommendation. If the user authorized implem
 
 ---
 
+## Dashboard and app panels
+
+A panel is used every day, so the bar is different from a landing page: motion that delights once tires on the tenth visit. When the project is a dashboard, admin or operational panel, cover these categories (only the ones the request or the map opens):
+
+- loading: skeleton, spinner, route progress, branded loader
+- action feedback: toast, confirmation, undo, a discreet success state
+- numbers: animated counter, sparkline, gauge, KPI card
+- lists and queues: enter/exit animation, swipe actions on mobile
+- navigation: sidebar, command menu, tooltip, dock
+- surfaces: hover states, border glow, spotlight, subtle background
+- empty states, charts and form controls
+
+For each candidate, judge "does it tire with daily use", reduced-motion support and weight. Reject landing-page effects that do not serve a task.
+
+---
+
 # Consistency rules
 
 If there is tension between the most impressive option and the best-fitting option: **choose the one that fits.**

package/tools/hooks/README.md

@@ -7,14 +7,26 @@ 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.                                                       |
+| `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). |
 
+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`. |
+
+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: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: `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/session-rules.js

@@ -11,8 +11,11 @@
 //   2. Feature ativa: resolve o `active_feature` SOZINHO, sem o usuário
 //      precisar invocar `wizz-set-feature` e responder duas perguntas. Ordem:
 //      branch git (mais fresco que o config) > `_wizz/bmm/config.yaml` > nada.
-//      Custo zero quando não há `_wizz/` nem branch de feature: a linha
-//      simplesmente não é emitida.
+//      Custo zero fora de projeto Wizz sem branch de feature: a linha
+//      simplesmente não é emitida. DENTRO de projeto Wizz sem feature sai um
+//      lembrete curto ("o primeiro pedido nomeado define uma", 2026-10-02):
+//      sem ele, projeto sem git ou na main ficava a vida toda sem feature
+//      (caso Spider). Mesmo lembrete para layout de pastas ausente.
 //
 //   3. Teto da auto-memória: o teto de 40 memórias e 8 KB de índice está
 //      escrito no CLAUDE.md global desde 2026-08-28, mas nada disparava a
@@ -39,163 +42,85 @@ const RULES =
   'concise communication by default, expand only on request; ' +
   'reply to the user in the language chosen at install (communication_language).';
 
-// Branches que NUNCA viram feature: são linha principal, não trabalho nomeado.
-const TRUNK = new Set(['main', 'master', 'develop', 'dev', 'staging', 'stage', 'prod', 'production', 'trunk', 'default', 'release']);
-
-// Branch de release/versão não é feature: nomeia um corte do produto, não um trabalho.
-const RELEASE_PREFIX = /^(release|rc|v)[/-]/i;
-
-// Prefixos de convenção que descrevem o TIPO do trabalho, não a feature.
-const TYPE_PREFIX = /^(feat|feature|fix|bugfix|hotfix|chore|refactor|docs|test|perf|ci|build|style)[/-]/i;
-
-/**
- * Normaliza um texto livre para o mesmo slug kebab-case que a skill
- * `wizz-set-feature` grava, para branch e config nunca divergirem por formato.
- * @param {string} raw
- * @returns {string} slug kebab-case, ou '' se não sobrar nada utilizável
- */
-function toSlug(raw) {
-  if (typeof raw !== 'string') return '';
-  return raw
-    .normalize('NFD')
-    .replaceAll(/[\u0300-\u036F]/g, '')
-    .toLowerCase()
-    .replaceAll(/[^a-z0-9]+/g, '-')
-    .replaceAll(/^-+|-+$/g, '')
-    .slice(0, 60);
+// 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.
+let lib = null;
+try {
+  lib = require('./wizz-feature-lib.js');
+} catch {
+  lib = null;
 }
 
-/**
- * Lê o branch atual sem subprocesso: `.git/HEAD` já traz o ref, e um read de
- * arquivo é mais barato e mais seguro que um `git` no PATH (que pode nem existir).
- * Sobe até 6 níveis para achar o `.git` de um subdiretório do repo.
- * @param {string} cwd
- * @returns {string} nome do branch, ou '' (detached HEAD, sem repo, erro)
- */
-function readGitBranch(cwd) {
-  let dir = cwd;
-  for (let i = 0; i < 6; i++) {
-    const gitPath = path.join(dir, '.git');
-    try {
-      const stat = fs.statSync(gitPath);
-      let headFile = path.join(gitPath, 'HEAD');
-      if (stat.isFile()) {
-        // worktree/submódulo: `.git` é um arquivo `gitdir: <caminho>`
-        const m = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(gitPath, 'utf8'));
-        if (!m) return '';
-        const resolved = path.resolve(dir, m[1].trim());
-        headFile = path.join(resolved, 'HEAD');
-      }
-      const head = fs.readFileSync(headFile, 'utf8').trim();
-      const ref = /^ref:\s*refs\/heads\/(.+)$/.exec(head);
-      return ref ? ref[1] : ''; // detached HEAD => sem branch => sem feature
-    } catch {
-      // segue subindo
-    }
-    const parent = path.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return '';
-}
+const HOOK_CMD = 'node _wizz/hooks/wizz-feature.js';
 
-/**
- * Deriva um slug de feature do nome do branch. Branch de tronco e branch sem
- * nome útil devolvem '' (nenhuma feature), nunca um slug inventado.
- * @param {string} branch
- * @returns {string}
- */
-function featureFromBranch(branch) {
-  if (!branch) return '';
-  if (TRUNK.has(branch.toLowerCase())) return '';
-  if (RELEASE_PREFIX.test(branch)) return '';
-  const stripped = branch.replace(TYPE_PREFIX, '');
-  const slug = toSlug(stripped);
-  if (!slug || TRUNK.has(slug)) return '';
-  // Branch que é só um número de issue não descreve feature nenhuma.
-  if (/^\d+$/.test(slug)) return '';
-  return slug;
-}
+const toSlug = (raw) => (lib ? lib.toSlug(raw) : '');
+const readGitBranch = (cwd) => (lib ? lib.readGitBranch(cwd) : '');
+const featureFromBranch = (branch) => (lib ? lib.featureFromBranch(branch) : '');
+const readConfigFeature = (root) => (lib ? lib.readConfigFeature(root) : { slug: '', configPath: '' });
+const findWizzRoot = (cwd) => (lib ? lib.findWizzRoot(cwd) : '');
 
 /**
- * Lê `active_feature` do config do módulo bmm. Parser de 1 chave de propósito:
- * o hook não pode depender de uma lib de YAML (roda fora do node_modules do repo).
- * @param {string} cwd
- * @returns {{slug: string, configPath: string}} slug '' quando ausente/vazio
+ * Lembretes de projeto Wizz que valem mesmo sem feature: nenhuma feature
+ * ativa (o primeiro pedido nomeado define uma), layout de pastas ausente e
+ * proposta de branch quando `feature_branches: auto`.
+ * @param {ReturnType<typeof lib.resolveFeature>} state
+ * @returns {string[]}
  */
-function readConfigFeature(cwd) {
-  const configPath = path.join(cwd, '_wizz', 'bmm', 'config.yaml');
-  try {
-    const text = fs.readFileSync(configPath, 'utf8');
-    const m = /^active_feature:\s*(.*)$/m.exec(text);
-    if (!m) return { slug: '', configPath };
-    const value = m[1]
-      .replace(/#.*$/, '')
-      .trim()
-      .replaceAll(/^["']|["']$/g, '');
-    return { slug: toSlug(value), configPath };
-  } catch {
-    return { slug: '', configPath };
+function wizzReminders(state) {
+  const out = [];
+  if (!state.slug) {
+    out.push(
+      `NENHUMA FEATURE ATIVA: o primeiro pedido nomeado (feature, lote, tela, bug com escopo) define uma. ` +
+        `Antes de despachar, derive o slug do pedido e grave: ${HOOK_CMD} definir <slug>. Sem perguntar; uma linha de confirmação.`,
+    );
+  } else if (state.featureBranches === 'auto' && state.git.isRepo && state.onTrunk) {
+    out.push(
+      `feature_branches: auto e você está em ${state.git.branch || 'HEAD solto'}: proponha em UMA linha \`git switch -c feat/${state.slug}\`.`,
+    );
   }
-}
-
-/**
- * Acha a raiz do projeto Wizz (a pasta que contém `_wizz/`) subindo do cwd.
- * O agente costuma rodar de uma subpasta, então checar só o cwd erraria.
- * @param {string} cwd
- * @returns {string} caminho da raiz, ou '' se não for projeto Wizz
- */
-function findWizzRoot(cwd) {
-  let dir = cwd;
-  for (let i = 0; i < 6; i++) {
-    try {
-      if (fs.existsSync(path.join(dir, '_wizz'))) return dir;
-    } catch {
-      // ignora e segue subindo
-    }
-    const parent = path.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
+  if (!state.hasLayout) {
+    out.push(
+      'PROJETO SEM LAYOUT DE PASTAS: no primeiro pedido, proponha a estrutura por tipo em UMA linha ' +
+        '(node _wizz/hooks/wizz-arrumar.js layout) e grave com `layout --gravar`. Arquivo novo nunca nasce solto na raiz.',
+    );
   }
-  return '';
+  return out;
 }
 
 /**
- * Monta a linha de contexto da feature. Devolve '' quando não há feature
- * nenhuma. Silêncio custa zero token e é o caso comum fora de projeto Wizz.
+ * Monta o contexto de feature. Fora de projeto Wizz e sem branch de feature
+ * devolve '' (silêncio custa zero token). Em projeto Wizz sem feature, sai o
+ * lembrete curto: é o que faz a organização acontecer sem o dono pedir.
  * @param {string} cwd
  * @returns {string}
  */
 function buildFeatureContext(cwd) {
-  const wizzRoot = findWizzRoot(cwd);
-  const isWizzProject = Boolean(wizzRoot);
-  const fromConfig = isWizzProject ? readConfigFeature(wizzRoot) : { slug: '', configPath: '' };
-  const fromBranch = featureFromBranch(readGitBranch(cwd));
-
-  // O branch ganha do config: é o que descreve o trabalho de AGORA. O config
-  // pode ter ficado numa feature antiga que ninguém lembrou de trocar.
-  const active = fromBranch || fromConfig.slug;
-  if (!active) return '';
+  if (!lib) return '';
+  const state = lib.resolveFeature(cwd);
+  const fromBranch = state.isWizz ? state.fromBranch : featureFromBranch(readGitBranch(cwd));
+  const active = state.isWizz ? state.slug : fromBranch;
+  const parts = [];
 
-  const parts = [
-    `FEATURE ATIVA: ${active}` + (fromBranch ? ' (derivada do branch git).' : ' (do config).'),
-    'Use como contexto sem perguntar nada:',
-    isWizzProject
-      ? `artefatos de planejamento e implementação vão para as subpastas ${active}/;`
-      : 'não é projeto Wizz, então não há subpasta de artefato;',
-    `memória gravada nesta sessão leva tema/feature "${active}".`,
-  ];
-
-  if (fromBranch && isWizzProject && fromConfig.slug !== fromBranch) {
+  if (active) {
+    parts.push(
+      `FEATURE ATIVA: ${active}` + (fromBranch ? ' (derivada do branch git).' : ' (do config).'),
+      'Use como contexto sem perguntar nada:',
+      state.isWizz
+        ? `artefatos de planejamento e implementação vão para as subpastas ${active}/ com nome <tipo>-<slug>.md (${HOOK_CMD} artefato <tipo>);`
+        : 'não é projeto Wizz, então não há subpasta de artefato;',
+      `memória gravada nesta sessão leva tema/feature "${active}".`,
+    );
+    if (fromBranch && state.isWizz && state.fromConfig !== fromBranch) {
+      parts.push(
+        `O config (_wizz/bmm/config.yaml) ainda diz "${state.fromConfig || 'vazio'}": grave "${active}" nele (${HOOK_CMD} definir ${active}) e avise em UMA linha.`,
+      );
+    }
     parts.push(
-      `O config (_wizz/bmm/config.yaml) ainda diz "${fromConfig.slug || 'vazio'}": grave "${active}" nele na primeira vez que escrever um artefato, e avise em UMA linha.`,
+      'NÃO peça confirmação de feature. Pedido de OUTRO assunto troca a feature (definir <novo>); continuação mantém. Pergunte só se houver ambiguidade real entre duas features abertas.',
     );
   }
-
-  parts.push(
-    'NÃO peça confirmação de feature. Só invoque a skill wizz-set-feature se o usuário pedir explicitamente para trocar, ou se houver ambiguidade real entre duas features abertas.',
-  );
-
+  if (state.isWizz) parts.push(...wizzReminders(state));
   return parts.join(' ');
 }