@lugom.io/hefesto 0.3.0 → 1.0.0

package/skills/hefesto-context/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: hefesto-context
-description: Conhecimento sobre a estrutura e convenções do Hefesto. Use sempre que o projeto tiver um diretório .hefesto/, quando o usuário mencionar features, specs, stories, roadmap ou estado do projeto no contexto do Hefesto, ou quando precisar entender como o .hefesto/ organiza o desenvolvimento.
+description: >
+  Conhecimento sobre estrutura e convenções do Hefesto (.hefesto/).
+  ATIVAR quando: projeto tem .hefesto/, usuário menciona feature/spec/story/roadmap/STATE.md/
+  PROJECT.md/config.json, qualquer skill hefesto-* precisa de contexto do sistema, ou tarefa
+  envolve IDs (FEAT-NNN, RES-NNN), status de features ou ciclo de desenvolvimento Hefesto.
+user-invocable: false
+disable-model-invocation: false
 ---
 
 # Hefesto Context
@@ -11,15 +17,14 @@ O Hefesto é um toolkit spec-driven + story-driven que organiza o desenvolviment
 
 ```
 .hefesto/
-├── PROJECT.md              # Visão, valor central, restrições do projeto
-├── ROADMAP.md              # Lista de features com status e progresso
-├── STATE.md                # Memória viva — posição atual, decisões, bloqueios (~80 linhas)
-├── config.json             # Configuração (counters de ID, runtime, preferências)
+├── PROJECT.md              # Visão, valor central, restrições, convenções e features
+├── STATE.md                # Memória entre sessões — posição, decisões, bloqueios (~80 linhas)
+├── config.json             # Configuração (projeto, plataforma, counters de ID)
+├── DESIGN.md               # Contrato visual (opcional, /hefesto-design)
 ├── features/               # Documentos narrativos unificados
 │   └── FEAT-NNN-slug.md    # Uma feature por arquivo
-├── research/               # Pesquisas estruturadas
-│   └── RES-NNN-slug.md     # Uma pesquisa por arquivo
-└── DESIGN.md               # Contrato de design do projeto (projeto-level)
+└── research/               # Pesquisas estruturadas
+    └── RES-NNN-slug.md     # Uma pesquisa por arquivo
 ```
 
 ## Features
@@ -49,14 +54,38 @@ Cada feature é um documento narrativo que combina **spec** (O QUÊ) e **stories
 - `done` — completa e verificada
 - `blocked` — bloqueada por dependência
 
+## UX: Interação com o Usuário
+
+- **Opções predefinidas** → sempre usar seletor interativo (não texto livre). Aplica-se a qualquer pergunta com respostas fixas: escolha de plataforma, confirmações sim/não, seleção entre alternativas, etc.
+- **Inputs abertos** → texto livre. Aplica-se a: nome do projeto, descrição, valor central, prazo, perguntas-chave, etc.
+
+## Ciclo de Vida Completo
+
+```
+init → (design) → new-feature → (research) → execute → validate → done
+  │       │            │              │          │          │
+  ▼       ▼            ▼              ▼          ▼          ▼
+/hefesto /hefesto   /hefesto     athena    /hefesto    argos
+ -init    -design   -new-feature  (agent)  -execute    (agent)
+                                             │
+                                             ├→ hermes (recon)
+                                             ├→ self-review inline
+                                             ├→ verification gate
+                                             │    └→ falha após retries → /hefesto-debug
+                                             ├→ /hefesto-simplify (pós)
+                                             ├→ /hefesto-security (pós)
+                                             └→ argos (QA loop, max 3x)
+```
+
 ## STATE.md
 
-Memória viva do projeto. Máximo ~80 linhas. Contém:
-- Posição atual (features feitas vs total)
+Memória entre sessões. Máximo ~80 linhas. Contém:
+
+- Posição atual (features feitas vs total, progresso)
 - Feature e fase ativa
 - Decisões recentes
 - Bloqueios
-- Informação de continuidade (última sessão, onde parou, como retomar)
+- Continuidade (última sessão, onde parou, como retomar)
 
 ## Pesquisas
 
@@ -68,31 +97,35 @@ Pesquisas estruturadas ficam em `.hefesto/research/` com IDs `RES-NNN`. São exe
 - **Vinculação**: podem ser linked a features via campo `feature` no frontmatter
 - Antes de pesquisar algo novo, verificar se já existe pesquisa relevante em `.hefesto/research/`
 
-## Design
-
-Contrato de design do projeto fica em `.hefesto/DESIGN.md` (projeto-level). Define direção estética, paleta de cores (60/30/10), tipografia (max 4 sizes, 2 weights), espaçamento (múltiplos de 4), copywriting e tokens de design. É criado via `/hefesto-design`.
+## Validação
 
-- **Escopo**: projeto-level (único por projeto)
-- **Status**: `draft` → `done`
-- **Profundidade**: `quick` (contrato básico), `standard` (completo com tokens), `deep` (com specs de componentes)
-- **6 Pilares de verificação**: Copywriting, Cores (60/30/10), Tipografia (≤4/2), Espaçamento (mult. 4), Hierarquia visual, Acessibilidade (AA)
-- **Scripts Python**: busca BM25 em bases curadas (estilos, cores, tipografia, UX), verificador de contraste WCAG, scanner de violações
-- **Referências**: 8 guides em `.claude/skills/hefesto-design/references/` (estética, tokens, componentes, UX, a11y, cores, checklist, anti-padrões)
+Após implementar features ou fases, delegue ao agente `hefesto-argos` para avaliação independente. O tester lê a spec, lê o código com olhar fresco (isolamento epistêmico), cria testes e retorna um veredicto estruturado (`approved` / `approved-with-notes` / `needs-work`). Delegue passando: Feature ID, fase(s) implementada(s) e paths dos arquivos alterados.
 
-## Validação
+## config.json
 
-Após implementar features ou fases, delegue ao agente `hefesto-argos` para avaliação independente. O tester lê a spec, lê o código com olhar fresco (isolamento epistêmico), cria testes e retorna um veredicto estruturado (`approved` / `approved-with-notes` / `needs-work`). Se o projeto tiver `.hefesto/DESIGN.md`, Argos também executa auditoria visual dos 6 pilares (score /24) usando scripts automatizados. Delegue passando: Feature ID, fase(s) implementada(s) e paths dos arquivos alterados.
+Metadados e contadores do projeto. Sempre leia `.hefesto/config.json` para valores atuais. Estrutura canônica em `.hefesto/templates/TPL-CONFIG.json`. Seções: `project`, `feature`, `research`, `design`, `verification`. O campo `project.language` define o idioma dos artefatos (default: `pt-BR`); `project.lang` define a linguagem de programação.
 
 ## Outputs
 
 Outputs reais (código, documentos, manifestos) vão para o projeto (src/, docs/, etc.). O `.hefesto/` apenas rastreia o que foi produzido e onde foi colocado.
 
+## Hooks
+
+- **hefesto-statusline.cjs** (StatusLine) — Exibe `⚒ HEFESTO | modelo | dir | contexto%` na statusline
+- **hefesto-check-update.cjs** (SessionStart) — Verifica versão nova no npm ao iniciar sessão
+- **hefesto-workflow.cjs** (PreToolUse) — Avisa quando Write/Edit é usado sem feature ativa
+
 ## Skills disponíveis
 
 - `/hefesto-init` — Inicializa .hefesto/ no projeto
-- `/hefesto-new-feature` — Cria nova feature
-- `/hefesto-update` — Atualiza o Hefesto
-- `/hefesto-design` — Cria/atualiza contrato de design do projeto
+- `/hefesto-new-feature` — Cria nova feature (com gate de validação)
+- `/hefesto-execute` — Executa implementação de feature (decomposição, verificação, QA loop)
+- `/hefesto-debug` — Debugging sistemático em 4 fases (causa raiz → padrão → hipótese → fix)
+- `/hefesto-design` — Cria contrato visual do projeto (cores, tipografia, componentes, tokens CSS)
+- `/hefesto-security` — Auditoria de segurança (OWASP, secrets, boundaries)
+- `/hefesto-simplify` — Simplificação e reuso de código (pós-implementação)
 - `hefesto-athena` — Agente de pesquisa estruturada (delegação automática)
-- `hefesto-argos` — Agente de teste e validação (delegação após implementação)
+- `hefesto-argos` — Agente de teste e validação (delegação após implementação, suporta QA loop)
 - `hefesto-hermes` — Agente batedor de codebase (reconhecimento antes de implementar)
+
+> **Nota:** Skills com `/` são invocadas diretamente pelo usuário. Agents sem `/` (athena, argos, hermes) são delegados automaticamente via subagent dispatch durante a execução — não são slash commands.

package/skills/hefesto-debug/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: hefesto-debug
+description: >
+  Debugging sistemático: investigar causa raiz antes de corrigir. 4 fases, máximo 3 tentativas.
+  ATIVAR quando: "bug", "erro", "quebrou", "não funciona", "debugar", "regressão",
+  "parou de funcionar", "tá dando erro", ou quando um comando/teste falha repetidamente
+  durante execução de outra tarefa.
+user-invocable: true
+disable-model-invocation: false
+argument-hint: '[descrição do problema]'
+---
+
+# Hefesto Debug
+
+Debugging sistemático que impõe disciplina: investigar antes de corrigir. Sem investigação, cada "tentativa" empilha patches frágeis que mascaram a causa real. Este workflow força o caminho correto: entender primeiro, corrigir depois.
+
+## Fase 1 — Causa Raiz (OBRIGATÓRIA)
+
+1. **Reproduzir**: rodar o comando/teste que falha, ler output COMPLETO (não só última linha)
+2. **Contexto**: `git diff`, `git log -5`, arquivos no fluxo do erro, spec da feature ativa (se houver)
+3. **Cadeia de erro**: sintoma → função → input → origem do input (rastrear para trás)
+4. **Output**: "A causa provável é [X] porque [evidência Y]. Manifesta em [Z], origina em [W]."
+
+Sinais de que está pulando investigação:
+
+- Propor solução antes de traçar o fluxo de dados
+- "Não entendo completamente mas..." — se não entende, não pode corrigir
+- Cada fix revela problema novo em lugar diferente → sinal arquitetural, pare e reavalie
+
+## Fase 2 — Análise de Padrões
+
+1. **Recorrência**: git log por fixes similares. Bug recorrente = problema estrutural
+2. **Profundidade**: módulo isolado ou atravessa camadas? Fix cria problemas em outro lugar?
+3. **Impacto**: módulos/features afetados, testes existentes, consumidores
+
+## Fase 3 — Teste de Hipóteses
+
+1. Formular 1-3 hipóteses específicas e refutáveis: "Se [causa], quando [teste], deveria [resultado]"
+2. Testar com mínima intervenção: logging, teste focado, UMA variável por vez
+3. Confirmada → Fase 4. Refutada → reformular. Todas refutadas → voltar à Fase 1
+
+## Fase 4 — Fix
+
+1. **Implementar fix mínimo**: causa raiz, não sintoma. Uma mudança por vez
+2. **Verificar**: comando original, `verification_commands` do config.json, regressões
+3. **Se falhar**: voltar à Fase 3 com hipótese refinada. Reverter, não empilhar
+4. **Após 3 tentativas**: PARAR. Listar premissas e tentativas. Sugerir revisão da abordagem
+5. **Se funcionar**: atualizar STATE.md, considerar teste de regressão
+
+## Integração com Hefesto
+
+- **Feature ativa**: ler spec para comportamento esperado, fix consistente com requisitos
+- **Verification commands**: usar de config.json na Fase 4
+- **Argos**: se bug durante `/hefesto-execute`, o debug é pausa no workflow — retomar após resolver

package/skills/hefesto-design/SKILL.md

@@ -1,194 +1,184 @@
 ---
 name: hefesto-design
 description: >
-  Cria ou atualiza o contrato de design do projeto (.hefesto/DESIGN.md).
-  Define direção estética, paleta de cores (60/30/10), tipografia (max 4 sizes, 2 weights),
-  espaçamento (mult. 4), copywriting e tokens de design. Pesquisa referências visuais
-  do domínio e aplica regras UX consolidadas. Inclui scripts Python para busca BM25
-  em base de dados de estilos, cores, tipografia e regras UX, além de verificadores
-  de contraste WCAG e scanner de violações no código.
-
-  Usar quando: definir identidade visual do projeto, criar design system,
-  escolher paleta/tipografia/espaçamento, antes de implementar features com UI,
-  ou quando o design atual parece genérico.
+  Contrato visual do projeto (.hefesto/DESIGN.md) — criação e enforcement do design system.
+  ATIVAR quando: .hefesto/DESIGN.md existe E tarefa envolve CSS, cores, fontes, componentes UI,
+  layout, Tailwind, styled-components, tema, dark mode, shadcn components ou qualquer decisão visual.
+  Também: /hefesto-design, "criar design", "paleta de cores", "design system", "identidade visual",
+  "look and feel", prototipar UI, fazer landing page.
 user-invocable: true
-disable-model-invocation: true
+disable-model-invocation: false
 ---
 
-## O que faz
+# Hefesto Design
 
-Cria ou atualiza `.hefesto/DESIGN.md` — contrato de design do **projeto inteiro**. Cada valor no DESIGN.md é um **contrato vinculante**: se está escrito `color: #3b82f6`, o executor usa `#3b82f6`. Sem interpretação, sem "adaptar".
+Cria o contrato visual do projeto (`.hefesto/DESIGN.md`) ou aplica durante implementação.
 
-3 níveis de profundidade:
-- **quick** — contrato básico (direção estética, cores, tipografia, espaçamento, copywriting, anti-padrões)
-- **standard** — + referências visuais pesquisadas + tokens de design (3 camadas)
-- **deep** — + specs de componentes (atomic design) + prompts para ferramentas AI (v0.dev/Lovable/Bolt)
+## Princípio
 
-## Como usar
+O contrato visual deve ter **ponto de vista**. Cada decisão — fonte, cor, radius, shadow — deve ser uma escolha intencional que reflete o projeto, não um default seguro. Se o resultado parece que qualquer AI geraria, está errado. O teste: alguém olhando o design consegue adivinhar que tipo de projeto é?
 
-```
-/hefesto-design                     # standard (default)
-/hefesto-design --depth quick       # apenas contrato básico
-/hefesto-design --depth deep        # inclui componentes e prompts AI
-```
+## Detecção de Modo
 
-## Mentalidade: contrato, não sugestão
+1. Se invocado como `/hefesto-design` → **Modo Criação**
+2. Se `/hefesto-design update` → **Modo Atualização**
+3. Se ativado automaticamente durante tarefa visual → **Modo Enforcement**
 
-Decisão vaga é pior que nenhuma decisão. O executor precisa de valores exatos (HEX, px, font-family), não "algo assim". Uma paleta "60/30/10 com tons de azul" é inútil — o executor precisa de `#0f172a`, `#1e293b`, `#3b82f6` com cada uso especificado.
+---
 
-O executor que consome o DESIGN.md trabalha em contexto isolado, sem memória da exploração. Ele precisa de:
-- **Valores exatos** — HEX, px, font-family, font-weight, line-height, border-radius
-- **Regras de uso** — quando usar cada cor, cada tamanho, cada peso
-- **Hierarquia clara** — o que é primário, secundário, terciário
-- **Restrições** — o que NUNCA fazer, anti-padrões específicos do projeto
+## Modo Criação
 
-## Pré-requisitos
+### Pré-requisitos
 
-- `.hefesto/` existe (senão, sugerir `/hefesto-init`)
-- `PROJECT.md` existe (lê contexto do projeto)
-- Python 3.8+ disponível (para scripts)
+Verificar se `.hefesto/` existe. Se não, sugerir `/hefesto-init`.
 
-## O que fazer
+### Fase 1 — Discovery
 
-### 1. Verificar estado
+Coletar informações com o usuário:
 
-1. Verificar que `.hefesto/` e `PROJECT.md` existem
-2. Ler `.hefesto/PROJECT.md` para entender contexto, público-alvo, tom e valores
-3. Se `.hefesto/DESIGN.md` já existe: perguntar ao usuário (atualizar / recriar / cancelar)
-4. Parse `--depth` (default: `standard`)
+1. **"Descreve teu projeto em uma frase"** — input aberto
+2. **"Quem é o público-alvo?"** — input aberto
+3. **"Em 3 palavras, que sentimento quer provocar?"** — input aberto (ex: confiança, energia, sofisticação)
+4. **Referência visual?** — seletor: URL de site / Imagem local (print/screenshot) / Descrição textual / Múltiplas fontes / Nenhuma
+   - Se URL: ler com WebFetch ou browser para extrair padrões visuais (cores, tipografia, layout)
+   - Se imagem: ler com Read tool para analisar padrões visuais (cores, tipografia, layout, componentes)
+   - Se descrição: usar como guia estético
+   - Se múltiplas fontes: aceitar combinação de URLs, imagens e descrições. Consolidar padrões visuais de todas as fontes numa síntese coerente, resolvendo conflitos pelo que melhor reflete o discovery
 
-### 2. Carregar referências
+**Antes de gerar**: com base nas respostas, comprometer-se com uma direção estética clara. Não buscar equilíbrio — buscar personalidade. Uma cor dominante com acentos afiados supera paletas distribuídas uniformemente. Uma fonte com caráter supera uma fonte "segura". Documentar a direção escolhida e o porquê em 1-2 frases antes de iniciar a geração.
 
-Localizar via Glob os recursos da skill:
+### Fase 2 — Geração
 
-```
-Glob: **/hefesto-design/references/*.md
-Glob: **/hefesto-design/scripts/*.py
-```
+1. Ler `.hefesto/templates/TPL-DESIGN.md` como guia de estrutura
+2. Gerar contrato **completo** — todas seções, todos componentes
+3. Cada valor é **exato**: HEX, px, font-family, CSS value. Zero ambiguidade
+4. Validar contrastes WCAG AA (ver seção Validação WCAG AA)
+5. Do's/Don'ts específicos deste projeto — se servem para qualquer projeto, são genéricos demais
+6. Validar contra Checklist de Qualidade (ver seção abaixo)
+7. Apresentar resumo para aprovação:
+   - Nome e descrição do design
+   - Paleta (brand + semantic)
+   - Tipografia (fonts + scale resumido)
+   - Filosofia (radius, shadows, spacing)
+   - 3 Do's e 3 Don'ts mais importantes
+8. Seletor: **Aprovar** / **Ajustar** (especificar o quê) / **Refazer** (novo discovery)
 
-Ler OBRIGATORIAMENTE antes de decidir:
+### Fase 3 — Gravação
 
-1. `aesthetics.md` — catálogo de 25+ estilos visuais com tipografia, paleta, uso
-2. `ux-rules.md` — regras UX por prioridade (WCAG, Material, Apple HIG)
-3. `anti-patterns.md` — o que NUNCA fazer (40 anti-padrões com alternativas)
+1. Salvar `.hefesto/DESIGN.md`
+2. Atualizar `.hefesto/config.json` → `design.status: "active"`
+3. Atualizar `.hefesto/STATE.md` com decisão
 
-Consultar conforme necessário:
+---
 
-4. `color-psychology.md` — significados de cores por indústria e cultura
-5. `token-architecture.md` — sistema de 3 camadas de tokens (standard+)
-6. `component-specs.md` — specs de componentes com estados e a11y (deep)
-7. `accessibility.md` — guia WCAG AA prático
-8. `checklist.md` — 33 verificações pre-delivery
-9. `polish.md` — micro-polish de interface (border radius, animações, sombras, hit areas)
+## Modo Enforcement
 
-### 3. Explorar com scripts
+Ativado automaticamente quando o modelo detecta tarefa visual (criar componente, CSS, Tailwind, estilizar, layout, tema, cores, fontes).
 
-Localizar scripts via Glob (`**/hefesto-design/scripts/*.py`) e executar:
+### Protocolo
 
-```bash
-# Recomendação completa de design system
-python3 {path}/design_system.py "{keywords do projeto}" -f json
+1. Ler `.hefesto/config.json` → `design.status`
+   - Se `"none"` → sair silenciosamente, sem output
+   - Se `"active"` → prosseguir
+2. Ler `.hefesto/DESIGN.md`
+3. **Todas** decisões visuais usam valores do contrato:
+   - Cores → paleta declarada
+   - Fontes → font stack declarado
+   - Tamanhos → type scale declarado
+   - Espaçamento → scale declarado
+   - Componentes → specs declaradas (estados, variantes, dimensões)
+   - Radius, shadows → filosofia declarada
+   - Animações → motion tokens declarados (durations, easings)
+4. Se o contrato **não cobre** algo necessário → **propor extensão** ao usuário, não inventar
+5. Se o contrato é ambíguo em algum ponto → perguntar ao usuário
 
-# Busca por domínio específico
-python3 {path}/search.py "{query}" --domain {domain} -f json
+---
 
-# Verificar contraste WCAG
-python3 {path}/contrast.py "{fg}" "{bg}"
+## Modo Atualização
 
-# Listar domínios disponíveis
-python3 {path}/search.py --list-domains
-```
+Invocado com `/hefesto-design update`.
 
-### 4. Pesquisar referências visuais (standard+)
+1. Ler `.hefesto/DESIGN.md` existente
+2. Perguntar o que quer ajustar (seletor: Cores / Tipografia / Componentes / Do's-Don'ts / Outro)
+3. Propor mudanças mantendo coerência com o restante do contrato
+4. Validar WCAG AA e checklist de qualidade
+5. Salvar com diff claro do que mudou
 
-Formular queries em **inglês** para maximizar cobertura:
-- `"{domain} website design {year}"` (ex: "fintech dashboard design 2026")
-- `"{aesthetic} UI examples"` (ex: "brutalist SaaS UI examples")
+---
 
-| Profundidade | Buscas web | Referências visuais |
-|--------------|------------|---------------------|
-| `quick`      | 1-2        | 0-1                 |
-| `standard`   | 3-5        | 3-5                 |
-| `deep`       | 6-10       | 6+                  |
+## Validação WCAG AA
 
-Para cada referência, registrar: URL, o que funciona, o que NÃO copiar.
+Fórmula para verificar contraste de cores inline, sem dependências externas:
 
-### 5. Derivar decisões do contexto
+```
+Converter HEX para sRGB (0-1):
+  R = parseInt(hex.slice(1,3), 16) / 255
+  G = parseInt(hex.slice(3,5), 16) / 255
+  B = parseInt(hex.slice(5,7), 16) / 255
+
+Linearizar cada canal:
+  Se C <= 0.03928 → C / 12.92
+  Senão → ((C + 0.055) / 1.055) ^ 2.4
+
+Luminância relativa:
+  L = 0.2126 * R + 0.7152 * G + 0.0722 * B
+
+Contrast ratio:
+  (L_lighter + 0.05) / (L_darker + 0.05)
 
-Cada decisão de design deve ser justificável:
-- **Público-alvo** → nível de sofisticação visual
-- **Domínio** → convenções do setor (fintech = confiança, saúde = calma, gaming = energia)
-- **Tom do projeto** → formal, casual, técnico, acessível
-- **Plataforma** → web, mobile, desktop, CLI
+Thresholds WCAG AA:
+  >= 4.5:1 — texto normal (< 18px regular, < 14px bold)
+  >= 3.0:1 — texto grande (>= 18px regular, >= 14px bold)
+```
 
-#### Overrides por Contexto (standard+)
+Verificar obrigatoriamente:
 
-Se o projeto tem áreas com necessidades visuais distintas:
+- Text Primary sobre Background
+- Text Primary sobre Surface
+- Text Secondary sobre Background
+- Text Secondary sobre Surface
+- Semantic colors (Success, Warning, Error) sobre Background
 
-1. Definir design system master para o contexto principal (>70% das telas)
-2. Para cada contexto secundário, definir **apenas** o que difere
-3. Cada override DEVE ter justificativa concreta
-4. Max 3 contextos — mais que isso = sistema mal definido
-5. Override não pode contradizer Anti-Padrões Bloqueados
+---
 
-### 6. Validar com dados
+## Anti-patterns
 
-- Contraste AA: verificar todos os pares fg/bg com `contrast.py`
-- Legibilidade: font-size mínimo 14px body, 12px labels
-- Touch targets: mínimo 44x44px mobile
-- Espaçamento: todos os valores em múltiplos de 4
+Erros comuns que o modelo comete ao gerar design systems. Detectar e corrigir antes de apresentar o contrato:
 
-### 7. Gerar DESIGN.md
+- **Contrato genérico** — Inter + blue primary + rounded 8px + subtle shadows = output padrão de qualquer modelo. Se o contrato parece genérico, refazer com mais personalidade baseada no discovery
+- **Inconsistência interna** — cores declaradas na paleta mas não usadas nos componentes, ou cores nos componentes que não existem na paleta
+- **Valores órfãos** — tokens mencionados em uma seção que não aparecem em outra
+- **Filosofia ausente** — listar valores sem explicar o "porquê". O Overview existe para dar contexto narrativo a cada decisão
+- **Componentes incompletos** — definir apenas default state, esquecendo hover, focus, active, disabled, error
+- **Do's/Don'ts genéricos** — "Use cores consistentes" ou "Mantenha espaçamento uniforme" servem para qualquer projeto. Cada regra deve ser consequência direta da filosofia deste design específico
+- **Spacing desalinhado** — base unit 8px mas usando valores como 10px, 15px, 22px que quebram o grid
+- **Contrastes não verificados** — declarar paleta sem rodar WCAG AA nas combinações text-on-surface
+- **Dark mode esquecido** — se o projeto suporta dark mode, todas surfaces e content colors precisam de variantes declaradas
+- **Default seguro** — escolher a fonte, cor ou layout "que funciona para tudo" é escolher nada. Cada valor deve ser consequência da direção estética, não uma aposta conservadora
+- **Convergência** — se o contrato resultante é indistinguível de outro projeto, falta personalidade. O discovery existe para diferenciar
 
-Usar o template de `.hefesto/templates/DESIGN.md`. Preencher os `{{PLACEHOLDER}}` com valores reais.
+---
 
-**Seções por profundidade:**
-- **quick**: §1-5 (Direção Estética, Cores, Tipografia, Espaçamento, Copywriting) + §10 (Anti-Padrões)
-- **standard**: quick + §6-8 (Referências Visuais, Tokens, Overrides por Contexto)
-- **deep**: standard + §9-10 (Specs de Componentes, Prompts AI)
+## Checklist de Qualidade
 
-Salvar em `.hefesto/DESIGN.md`. Atualizar `.hefesto/STATE.md` com referência ao design.
+Validar antes de apresentar o contrato ao usuário:
 
-## Princípio anti-genérico
+- [ ] **Completude** — todas seções do TPL-DESIGN.md preenchidas com valores reais?
+- [ ] **Coerência narrativa** — Overview reflete as decisões visuais? Do's/Don'ts derivam da filosofia?
+- [ ] **Especificidade** — todos valores são copy-paste ready (HEX, px, font-family, CSS value)? Nenhum "algo como" ou "variação de"?
+- [ ] **Consistência interna** — tokens usados nos componentes batem com a paleta? Font specs batem com o type scale?
+- [ ] **WCAG AA** — todas combinações text-on-surface verificadas com a fórmula?
+- [ ] **Componentes completos** — todos estados definidos (default, hover, active, focus, disabled)?
+- [ ] **Anti-patterns** — nenhum item da lista acima presente no contrato?
+- [ ] **Personalidade** — o contrato reflete o projeto, não um template genérico?
+- [ ] **Memorabilidade** — alguém vendo apenas a paleta + tipografia consegue intuir o tipo de projeto?
 
-NUNCA convergir em escolhas comuns entre projetos. Inter/Roboto/Arial estão **BLOQUEADOS** como choices padrão. Purple gradients on white estão **BLOQUEADOS**. Cada design deve parecer genuinamente projetado para o contexto. Maximalist bold e minimalist refinado ambos funcionam — o ponto é intencionalidade, não intensidade.
+---
 
 ## Regras
 
-- Todos os textos no DESIGN.md em Português BR
-- Valores sempre exatos (HEX, px, font-family) — nunca "tons de azul" ou "espaçamento generoso"
-- Contraste AA verificado para todos os pares de cores
-- Max 4 tamanhos de fonte, max 2 pesos
-- Espaçamento só em múltiplos de 4
-- CTAs com verbos específicos, nunca genéricos ("Criar conta" não "Clique aqui")
-- Inter/Roboto/Arial bloqueados — justifique qualquer fonte genérica
-- Nunca invente URLs de referência
-
-## Scripts disponíveis
-
-| Script | Comando | Quando usar |
-|--------|---------|-------------|
-| Design System | `design_system.py "keywords"` | Recomendação completa |
-| Busca | `search.py "query" --domain style` | Buscar estilos, cores, tipografia, etc. |
-| Contraste | `contrast.py "#hex1" "#hex2"` | Validar pares de cores (WCAG AA) |
-| Auditoria | `audit.py --design .hefesto/DESIGN.md --src src/` | Scan violações contra contrato |
-| Tokens | `validate_tokens.py --design .hefesto/DESIGN.md --src src/` | Verificar uso de tokens |
-| Domínios | `search.py --list-domains` | Ver domínios de busca |
-
-## Domínios de busca
-
-| Domínio | CSV | Descrição |
-|---------|-----|-----------|
-| `style` | `styles.csv` | Direções estéticas e atributos visuais |
-| `color` | `colors.csv` | Paletas por indústria e mood |
-| `typography` | `typography.csv` | Font pairings e hierarquia |
-| `component` | `components.csv` | Specs de componentes e variantes |
-| `ux` | `ux-rules.csv` | Regras UX por prioridade |
-| `anti-pattern` | `anti-patterns.csv` | Anti-padrões com alternativas |
-| `spacing` | `spacing.csv` | Escalas de espaçamento |
-| `animation` | `animations.csv` | Presets de animação |
-| `product` | `products.csv` | Tipos de produto e recomendações de design |
-| `chart` | `charts.csv` | Gráficos e visualização de dados |
-| `landing` | `landing-pages.csv` | Seções de landing page |
-| `icon` | `icons.csv` | Icon sets por estilo e contexto |
-| `font` | `google-fonts.csv` | Google Fonts com metadata e pairings |
+- **DESIGN.md em Inglês** — o contrato é consumido por agentes e código
+- **Zero dependências** — validação WCAG AA inline, sem scripts
+- **Valores exatos** — nunca gerar "algo entre X e Y" ou "variação de"
+- **Font stack com fallbacks** — sempre incluir fallback CSS completo (system fonts)
+- **Filosofia explícita** — border radius, shadows e spacing devem ter justificativa, não apenas valores