@fontdata/ai-harness 2.0.0 → 2.1.0

package/templates/rules/comentarios.md

@@ -0,0 +1,166 @@
+# Estilo de comentários (todas as linguagens)
+
+IMPORTANT: o padrão é **não comentar**. Comentário é exceção que precisa se justificar.
+
+Antes de escrever qualquer comentário, responda:
+**"quem editar esta linha daqui a 6 meses quebra o sistema sem esta informação?"**
+Se a resposta não for um "sim" claro, **não comente**.
+
+## Orçamento (limites duros)
+
+| Item | Limite |
+|---|---|
+| Bloco de comentário interno | **3 linhas** |
+| Docstring de função/método público | **5 linhas** |
+| Cabeçalho de arquivo | **proibido** |
+| Comentários internos por função | **1** |
+| Densidade do arquivo | **<= 10%** das linhas |
+
+Se o porquê não cabe em 3 linhas, **ele não pertence ao código**.
+
+## Proibido
+
+1. **Banner/separador de seção** — `// ─── X ───`, `// ==== SEÇÃO ====`, `// ---- X ----`.
+   Arquivo que precisa de seções precisa ser **dividido**, não decorado.
+2. **Rastreabilidade de processo** — `Task 4.2.1`, `Fase 2`, `Plano 006`, `T2.1`, `SPEC 001`,
+   `docs/trabalhos/...`, `achado do @code-reviewer`, `commit c83bb4e0`, `bug de 2026-07-16`.
+   O git e `docs/` já guardam isso; no código vira lixo em três meses.
+3. **Narração do passo a passo** — `// Carrega o usuário`, `// Verifica se existe`, `// Monta o payload`.
+4. **Redundância com o identificador** — `// Mapa de nó por id` acima de `const nodeMap = new Map()`.
+5. **Ensaio/investigação** — medição, histórico do bug, o que foi tentado, o que foi rejeitado.
+   Isso vive nos relatórios do trabalho em `docs/trabalhos/`, não no código.
+6. **Ênfase tipográfica** — CAPS-LOCK (`NUNCA`, `IMPOSSÍVEL`), emoji, `⚠️ REGRA DE OURO`.
+7. **Código comentado** — apague; o git guarda.
+
+## Permitido (lista fechada)
+
+- **Contrato não óbvio** de função/método público — docstring de até 5 linhas.
+- **Armadilha real**: por que a abordagem óbvia quebra — até 3 linhas, **no presente**, sem contar a história.
+- **`TODO:` / `FIXME:`** com o motivo real — 1 linha.
+- **Referência externa** (RFC, issue da lib, doc de API) que justifica um workaround — 1 linha.
+
+## Para onde vai cada informação
+
+| Informação | Onde mora | Nunca em |
+|---|---|---|
+| Por que a mudança foi feita | mensagem de commit | comentário |
+| Task / fase / plano / spec | `PLAN.md` e `SPEC.md` do trabalho em `docs/trabalhos/<id>/` | comentário |
+| Diagnóstico e correção de um defeito | trabalho do tipo `bug` em `docs/trabalhos/<id>/` | comentário |
+| Investigação, medição, auditoria, paridade, comparação | relatórios do trabalho em `docs/trabalhos/<id>/relatorios/` | comentário |
+| Achado de review | resposta do review, commit | comentário |
+| Decisão de arquitetura | `SPEC.md` | comentário |
+| Armadilha ao editar **aquela linha** | comentário de até 3 linhas | — |
+
+**Que tipo de trabalho?** Defeito com os três — sintoma reproduzível, causa raiz identificada e
+correção aplicada no código — é trabalho do tipo `bug` (`/resolver-bug`). Se falta qualquer um — é
+auditoria, paridade com legado, medição, comparação, levantamento, handoff ou follow-up — é
+`auditoria` ou `investigacao`. Se o documento descreve trabalho a fazer, é `feature` (`/nova-tarefa`).
+
+Convenção: uma pasta por trabalho, `docs/trabalhos/<yyyy-mm-dd>-<slug>/`.
+
+## Antes e depois
+
+**1. Ensaio de investigação → armadilha objetiva**
+
+```ts
+// ANTES (7 linhas: medição, histórico e ênfase)
+// Timeout PRÓPRIO (independente do timeout global de query do Baileys) para a busca
+// da foto de perfil no recebimento. Medição real: com o timeout global em 60000ms,
+// todo recebimento de contato LID (que não responde à query w:profile:picture)
+// travava por ~60s; baixando para 15000ms o atraso caiu para 15.001ms — proporcional
+// ao milissegundo. A foto é cosmética e NUNCA pode bloquear o recebimento; default
+// SEGURO e curto, sem depender de NODE_ENV.
+PROFILE_PIC_TIMEOUT_MS: z.coerce.number().default(3000),
+
+// DEPOIS (2 linhas: só o que quebra ao editar esta linha)
+// Contato LID nunca responde a essa query e a foto é cosmética — subir este timeout
+// volta a travar o recebimento de mensagem.
+PROFILE_PIC_TIMEOUT_MS: z.coerce.number().default(3000),
+```
+
+**2. Cabeçalho de arquivo → nada**
+
+```ts
+// ANTES (49 linhas antes do primeiro import)
+/**
+ * Task 1.3.4 / Task 2.3.7 — AgentFlowExecutor
+ *
+ * Orquestra a execução de um AgentRun:
+ *   1. Carrega AgentRun escopado por id + companyId (multi-tenant)
+ *   2. Adquire lock por ticket
+ *   ...
+ * GRAFO DINÂMICO (Fase 2):
+ * ROTEAMENTO POR builderMode (Plano 006 — modo simples, T2.1):
+ */
+import { ... }
+
+// DEPOIS
+import { ... }
+```
+
+O nome do arquivo, os exports e a assinatura pública já dizem o que ele é. A ordem dos passos está no
+código; a história está no git.
+
+**3. Banner + narração → código legível**
+
+```ts
+// ANTES
+// ── 1. Carrega AgentRun escopado por id + companyId ─────────────────
+const run = await AgentRun.findOne({ where: { id, companyId } });
+// ── 2. Adquire lock por ticket ──────────────────────────────────────
+const lock = await acquireTicketLock(companyId, ticketId);
+
+// DEPOIS
+const run = await AgentRun.findOne({ where: { id, companyId } });
+const lock = await acquireTicketLock(companyId, ticketId);
+```
+
+**4. Docstring inflada → contrato**
+
+```ts
+// ANTES (12 linhas)
+/**
+ * Gera um novo par de chaves de API para a empresa.
+ * Task 7.3.1. Esta função foi criada no plano de 2026-07-28 depois que o
+ * @code-reviewer apontou que a chave estava sendo salva em texto puro.
+ * Primeiro gera bytes aleatórios, depois deriva o hash SHA-256, e por fim
+ * ...
+ */
+
+// DEPOIS (4 linhas)
+/**
+ * Gera um par (plainKey, keyHash).
+ * - plainKey: devolvido UMA única vez ao chamador, nunca persistido
+ * - keyHash: o que vai para o banco
+ */
+```
+
+## Sintaxe por linguagem
+
+```ts
+/**
+ * Uma linha de propósito; entradas/saídas só quando não são óbvias.
+ */
+export function hashApiKey(plainKey: string): string {}
+```
+
+```pascal
+/// <summary>
+///   Gera o hash SHA-256 de uma API Key.
+/// </summary>
+function HashApiKey(const APlainKey: string): string;
+```
+
+- **TypeScript/JavaScript/Java/C#/C++/Go/Rust/PHP:** `/** ... */` no topo do símbolo **público**.
+- **Python:** docstring `"""..."""` curta logo abaixo da assinatura.
+- **Delphi/Pascal:** `///` (XMLDoc) nas rotinas públicas da `interface`; nunca repetir na `implementation`.
+- **SQL/Shell/YAML:** somente regra de negócio ou pegadinha não evidente.
+
+## Enforcement
+
+O hook `.claude/hooks/comentarios/check.mjs` roda a cada `Write`/`Edit` e **bloqueia** banner, rastreabilidade
+de processo, data, cabeçalho de arquivo, código comentado e bloco acima do teto.
+
+Arquivos que já existiam quando o padrão foi instalado estão em
+`.claude/hooks/comentarios/baseline.json` (catraca): eles **não precisam ser limpos de uma vez**, só não
+podem piorar. Quando melhoram, a catraca desce e não volta.

package/templates/rules/harness-projeto.md

@@ -0,0 +1,41 @@
+# Harness do projeto
+
+Rule de convenção do ai-harness. As skills `/nova-tarefa`, `/resolver-bug` e `/executar-plan` e os agents `qa` e
+`revisor-testes` leem este arquivo para saber o que é específico deste projeto. Preencha as seções que valem, apague
+as que não valem e mantenha o texto curto: é contexto carregado em toda sessão.
+
+## Mapa de agents por domínio
+
+Quem implementa cada área. O `/executar-plan` delega cada task ao agent do domínio dela.
+
+| Domínio ou pasta | Agent | Observação |
+|---|---|---|
+| _ex.: `apps/api/`_ | _`backend-dev`_ | _mudança estrutural passa antes pelo `arquiteto`_ |
+
+## Portões extras
+
+Portões que valem além de `revisor-testes` e `qa`, na ordem em que acontecem.
+
+- _ex.: `code-reviewer` em contexto limpo ao fim de cada task_
+- _ex.: aprovação humana antes de migration, webhook ou mudança multi-tenant_
+
+## Suíte de testes
+
+- **Comando:** _ex.: `docker compose exec test composer test`_
+- **Onde roda:** _ex.: container `test`; o PHP do host não serve_
+- **Checagens extras:** _ex.: `phpstan` e `pint`_
+
+## Verificação manual
+
+Para área sem testes automatizados, como Delphi sem build por linha de comando.
+
+- **Onde vale:** _ex.: `Fontes/`_
+- **Roteiro:** _os passos que o `qa` confere, cada um com evidência_
+
+Nessa área, o `qa` registra `suite_verde` com `"comando":"manual"`, `total` igual ao número de itens do roteiro e
+`falhas` igual a 0; com item reprovado, `suite_vermelha`.
+
+## Comandos legados a extrair
+
+Comandos personalizados que o `update` renomeou para `-legado`. Leve para as seções acima o que for do projeto e
+apague o arquivo.

package/templates/skills/auditar-performance/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: auditar-performance
+description: Audita gargalos de performance — tela lenta, consulta que demora, travamento ou timeout — em queries, backend, bundle, renders e algoritmos, medindo antes de recomendar.
+argument-hint: "[foco opcional: 'backend', 'frontend', 'tela X', 'endpoint Y']"
+---
+
+# Auditoria de performance
+
+Foco (opcional): $ARGUMENTS
+
+Sem foco, analise o projeto como um todo e priorize os pontos de maior impacto. **Não altere código** e não
+instale ferramentas novas sem perguntar.
+
+## Passo 1 — Criar o trabalho de auditoria
+
+1. Id `AAAA-MM-DD-auditoria-performance` (ou com o foco no slug).
+2. Registre o início:
+
+   ```bash
+   npx @fontdata/ai-harness evento trabalho_iniciado --trabalho <id> --nome auditar-performance --dados '{"trabalho_tipo":"auditoria"}'
+   ```
+
+## Passo 2 — Analisar
+
+Identifique a stack e percorra os pontos quentes de `references/pontos-quentes.md`. **Meça em vez de adivinhar**
+sempre que possível: profiler, `EXPLAIN`, análise de bundle, tempos em log ou teste de carga já existente.
+Achado sem medição é marcado como estimativa.
+
+Para cada achado: evidência (`arquivo:linha` e a medição), **impacto** (alto, médio, baixo), **esforço** de correção
+e a correção recomendada.
+
+## Passo 3 — Relatório técnico
+
+Grave `docs/trabalhos/<id>/relatorios/TECNICO.md` a partir de `templates/relatorios/TECNICO.md`, com os achados
+priorizados por impacto e esforço e o que foi medido (comando e resultado). Preencha `arquivos`.
+
+## Passo 4 — Relatório para a gestão
+
+Grave `docs/trabalhos/<id>/relatorios/CLIENTE.md` a partir de `templates/relatorios/CLIENTE.md`: onde as pessoas
+esperam, quanto, o ganho esperado com cada prioridade e o esforço relativo — **sem jargão técnico**.
+
+Registre os relatórios e o encerramento, e marque os dois como `final`:
+
+```bash
+npx @fontdata/ai-harness evento relatorio_gerado --trabalho <id> --nome auditar-performance --dados '{"caminho":"docs/trabalhos/<id>/relatorios/TECNICO.md"}'
+npx @fontdata/ai-harness evento relatorio_gerado --trabalho <id> --nome auditar-performance --dados '{"caminho":"docs/trabalhos/<id>/relatorios/CLIENTE.md"}'
+npx @fontdata/ai-harness evento trabalho_concluido --trabalho <id> --nome auditar-performance
+```
+
+## Passo 5 — Próximos passos
+
+As otimizações aprovadas seguem por `/nova-tarefa`, citando o id desta auditoria e a medição de referência, para
+que o ganho seja comprovado depois.

package/templates/skills/auditar-performance/references/pontos-quentes.md

@@ -0,0 +1,35 @@
+# Pontos quentes de performance
+
+## Banco de dados
+
+- Consultas N+1 (consulta dentro de laço, carregamento preguiçoso em lista).
+- Falta de índice nas colunas de filtro, junção e ordenação — confirme com `EXPLAIN`.
+- `SELECT *` trazendo colunas pesadas; paginação ausente em listagens.
+- Transações longas e bloqueios; chamadas repetidas com os mesmos parâmetros.
+
+## Backend
+
+- Trabalho síncrono bloqueante em requisição (arquivos, integrações, criptografia).
+- Ausência de cache para dados que mudam pouco; cache sem expiração.
+- Serialização cara ou repetida; I/O repetido no mesmo fluxo.
+- Integração externa sem timeout, sem paralelismo onde é possível.
+
+## Frontend
+
+- Tamanho do bundle e imports pesados carregados na primeira tela.
+- Re-renderizações desnecessárias; listas grandes sem virtualização.
+- Imagens sem otimização; ausência de carregamento sob demanda.
+
+## Algoritmos
+
+- Complexidade evitável (O(n²) em laços aninhados sobre coleções grandes).
+- Estrutura de dados inadequada (busca linear onde cabe mapa ou conjunto).
+
+## Como medir
+
+| Camada | Ferramenta típica |
+|---|---|
+| Banco | `EXPLAIN`/`EXPLAIN ANALYZE`, log de consultas lentas |
+| Backend | profiler da linguagem, tempos por etapa em log |
+| Frontend | análise de bundle, painel de performance do navegador |
+| Ponta a ponta | teste de carga já existente no projeto |

package/templates/skills/auditar-performance/templates/relatorios/CLIENTE.md

@@ -0,0 +1,26 @@
+---
+schema_versao: 1
+tipo: relatorio_cliente
+id: "{{id}}"
+trabalho_tipo: auditoria
+titulo: "{{titulo}}"
+status: rascunho
+criado_em: "{{data}}"
+atualizado_em: "{{data}}"
+arquivos: []
+---
+
+# {{titulo}}
+
+## Onde as pessoas esperam
+
+As telas e operações mais demoradas e quanto tempo levam hoje.
+
+## O que ganhamos com cada melhoria
+
+1. Primeira prioridade: ganho esperado e esforço relativo.
+2. Segunda prioridade.
+3. Terceira prioridade.
+
+## O que já está bom
+

package/templates/skills/auditar-performance/templates/relatorios/TECNICO.md

@@ -0,0 +1,27 @@
+---
+schema_versao: 1
+tipo: relatorio_tecnico
+id: "{{id}}"
+trabalho_tipo: auditoria
+titulo: "{{titulo}}"
+status: rascunho
+criado_em: "{{data}}"
+atualizado_em: "{{data}}"
+arquivos: []
+---
+
+# Auditoria de performance — {{titulo}}
+
+## Escopo e medições
+
+O que foi analisado, com quais ferramentas e os números de referência.
+
+## Achados priorizados
+
+| # | Achado | Evidência | Medição | Impacto | Esforço | Correção recomendada |
+|---|---|---|---|---|---|---|
+| 1 | | `arquivo:linha` | | alto | baixo | |
+
+## Estimativas sem medição
+
+Achados que precisam de medição antes de virar trabalho.

package/templates/skills/auditar-seguranca/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: auditar-seguranca
+description: Auditoria de segurança e LGPD — procura vulnerabilidade, segredo ou token exposto, dados pessoais sem proteção, dependências vulneráveis, inputs sem validação e configurações inseguras.
+argument-hint: "[foco opcional: 'só segurança', 'só lgpd', 'autenticação'...]"
+---
+
+# Auditoria de segurança e LGPD
+
+Foco (opcional): $ARGUMENTS
+
+Auditoria **defensiva** do próprio projeto, em duas frentes: **segurança técnica** e **conformidade com a LGPD**.
+Se o foco restringir o escopo, respeite-o; sem foco, rode as duas frentes. **Não altere código.**
+
+## Passo 1 — Criar o trabalho de auditoria
+
+1. Id `AAAA-MM-DD-auditoria-seguranca` (ou com o foco no slug).
+2. Registre o início:
+
+   ```bash
+   npx @fontdata/ai-harness evento trabalho_iniciado --trabalho <id> --nome auditar-seguranca --dados '{"trabalho_tipo":"auditoria"}'
+   ```
+
+## Passo 2 — Segurança técnica
+
+Siga o checklist de `references/seguranca-tecnica.md`: segredos, dependências, validação de entrada,
+autenticação e autorização, configuração. Classifique cada achado em **CRÍTICO / ALTO / MÉDIO / BAIXO**, com
+evidência (`arquivo:linha`) e correção recomendada. **Nunca** copie o valor de um segredo para o relatório — só a
+localização.
+
+## Passo 3 — Conformidade com a LGPD
+
+Use a skill **`lgpd-checker`** (no plugin, `fontdata:lgpd-checker`) e siga as fases dela:
+
+- **Reconhecimento:** tipo de aplicação, stack e se o sistema trata dados pessoais. Se não tratar, registre a
+  justificativa e pule esta frente.
+- **Análise por categoria** (CAT-1 a CAT-11), com busca ativa no código — não presuma conformidade.
+- **Severidade e veredito:** cada achado com o artigo da LGPD e recomendação concreta; veredito ✅ CONFORME,
+  ⚠️ PARCIALMENTE CONFORME ou ❌ NÃO CONFORME.
+
+A CAT-4 (segurança técnica) se sobrepõe ao Passo 2: registre o achado uma vez no Passo 2 e referencie-o na CAT-4.
+Categoria sem código para avaliar é dita explicitamente, não presumida.
+
+## Passo 4 — Relatório técnico
+
+Grave `docs/trabalhos/<id>/relatorios/TECNICO.md` a partir de `templates/relatorios/TECNICO.md`: sumário por
+severidade e veredito LGPD, achados críticos primeiro, segurança técnica, conformidade LGPD por categoria (no
+formato do relatório da `lgpd-checker`), pontos positivos e plano de ação priorizado. Preencha `arquivos` com os
+arquivos citados.
+
+## Passo 5 — Relatório para a gestão
+
+Grave `docs/trabalhos/<id>/relatorios/CLIENTE.md` a partir de `templates/relatorios/CLIENTE.md`: os riscos em
+linguagem de negócio (o que pode acontecer, com quem, qual a exposição legal), o veredito LGPD e as três
+prioridades — **sem jargão técnico**.
+
+Registre os relatórios e o encerramento, e marque os dois como `final`:
+
+```bash
+npx @fontdata/ai-harness evento relatorio_gerado --trabalho <id> --nome auditar-seguranca --dados '{"caminho":"docs/trabalhos/<id>/relatorios/TECNICO.md"}'
+npx @fontdata/ai-harness evento relatorio_gerado --trabalho <id> --nome auditar-seguranca --dados '{"caminho":"docs/trabalhos/<id>/relatorios/CLIENTE.md"}'
+npx @fontdata/ai-harness evento trabalho_concluido --trabalho <id> --nome auditar-seguranca
+```
+
+## Passo 6 — Próximos passos
+
+Achados que viram correção seguem por `/resolver-bug` (defeito pontual) ou `/nova-tarefa` (adequação maior),
+citando o id desta auditoria.

package/templates/skills/auditar-seguranca/references/seguranca-tecnica.md

@@ -0,0 +1,23 @@
+# Checklist de segurança técnica
+
+1. **Segredos:** chaves de API, senhas, tokens e credenciais no código e no histórico recente
+   (`git log -p` nos arquivos de configuração). `.env` fora do controle de versão; `.env.example` só com
+   valores de exemplo.
+2. **Dependências:** rode o auditor da stack quando disponível (`npm audit`, `pip-audit`, `dotnet list package
+   --vulnerable`, `osv-scanner`) e liste as vulnerabilidades por severidade. Não instale ferramenta nova sem
+   perguntar.
+3. **Validação de entrada:** inputs sem validação ou sanitização — injeção (SQL, comando, XSS), path traversal,
+   desserialização insegura, upload sem verificação de tipo e tamanho.
+4. **Autenticação e autorização:** rotas sem proteção, checagem de permissão ausente ou só no front, sessão ou
+   token com segredo fraco ou sem expiração, isolamento entre empresas/tenants, CORS permissivo demais.
+5. **Configuração:** modo debug em produção, cabeçalhos de segurança ausentes, TLS, stack trace exposto ao
+   usuário, logs com dados pessoais ou segredos.
+
+## Severidade
+
+| Nível | Quando |
+|---|---|
+| **CRÍTICO** | Exploração direta, sem autenticação, com vazamento ou alteração de dados |
+| **ALTO** | Exploração exige alguma condição (usuário autenticado, rede interna), com impacto relevante |
+| **MÉDIO** | Enfraquece a defesa, mas não é explorável sozinho |
+| **BAIXO** | Boa prática ausente, impacto pequeno |

package/templates/skills/auditar-seguranca/templates/relatorios/CLIENTE.md

@@ -0,0 +1,30 @@
+---
+schema_versao: 1
+tipo: relatorio_cliente
+id: "{{id}}"
+trabalho_tipo: auditoria
+titulo: "{{titulo}}"
+status: rascunho
+criado_em: "{{data}}"
+atualizado_em: "{{data}}"
+arquivos: []
+---
+
+# {{titulo}}
+
+## Situação geral
+
+Resumo em poucas frases e a situação em relação à Lei Geral de Proteção de Dados.
+
+## Principais riscos
+
+O que pode acontecer, com quem e qual a exposição para a empresa.
+
+## Prioridades
+
+1. O que resolver primeiro e por quê.
+2. Segunda prioridade.
+3. Terceira prioridade.
+
+## O que já está bem
+

package/templates/skills/auditar-seguranca/templates/relatorios/TECNICO.md

@@ -0,0 +1,38 @@
+---
+schema_versao: 1
+tipo: relatorio_tecnico
+id: "{{id}}"
+trabalho_tipo: auditoria
+titulo: "{{titulo}}"
+status: rascunho
+criado_em: "{{data}}"
+atualizado_em: "{{data}}"
+arquivos: []
+---
+
+# Auditoria de segurança e LGPD — {{titulo}}
+
+## Sumário
+
+| Frente | Crítico | Alto | Médio | Baixo |
+|---|---|---|---|---|
+| Segurança técnica | 0 | 0 | 0 | 0 |
+| LGPD | 0 | 0 | 0 | 0 |
+
+Veredito LGPD: CONFORME, PARCIALMENTE CONFORME ou NÃO CONFORME.
+
+## Achados críticos
+
+## Segurança técnica
+
+Cada achado: severidade, `arquivo:linha`, descrição e correção recomendada.
+
+## Conformidade LGPD
+
+Achados por categoria (CAT-1 a CAT-11), com o artigo da lei e a recomendação.
+
+## Pontos positivos
+
+## Plano de ação
+
+Em ordem de prioridade.

package/templates/skills/auditar-ui/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: auditar-ui
+description: Navega a aplicação via Playwright MCP e audita UX/UI e/ou acessibilidade (a11y, WCAG AA), gerando relatório técnico por tela e severidade e um resumo para a gestão.
+argument-hint: "[lente ux|a11y|tudo] [url] [usuário] [senha]"
+---
+
+# Auditoria de interface via navegador
+
+Parâmetros: $ARGUMENTS
+
+Usando o **MCP do Playwright**, abra o navegador **na tela do usuário**, para que ele acompanhe a navegação.
+**Não altere código** — apenas reporte o que precisa ser criado ou melhorado.
+
+## Passo 0 — Parâmetros
+
+São necessários quatro. O que **não** veio nos parâmetros, **pergunte antes de abrir o navegador**, oferecendo o
+exemplo como padrão:
+
+- **Lente:** `ux`, `a11y` ou `tudo` — padrão `tudo`;
+- **URL** da aplicação (ex.: `http://localhost:3000`);
+- **Usuário** para login (ex.: `admin@admin.com.br`);
+- **Senha** para login (ex.: `admin`).
+
+A senha nunca vai para os relatórios nem para o rastro.
+
+## Passo 1 — Criar o trabalho de auditoria
+
+1. Id `AAAA-MM-DD-auditoria-ui` (ou `-a11y`, conforme a lente).
+2. Registre o início:
+
+   ```bash
+   npx @fontdata/ai-harness evento trabalho_iniciado --trabalho <id> --nome auditar-ui --dados '{"trabalho_tipo":"auditoria"}'
+   ```
+
+## Passo 2 — Navegar e auditar
+
+1. Faça login e percorra **todas** as telas, clicando em todos os menus e botões.
+2. Em cada tela, aplique a lente escolhida com o checklist de `references/lentes.md`.
+3. Classifique cada achado: **CRÍTICO** (bloqueia o uso), **SÉRIO**, **MODERADO** ou **MENOR**, citando o critério
+   **WCAG** nos achados de acessibilidade.
+
+## Passo 3 — Relatório técnico
+
+Grave `docs/trabalhos/<id>/relatorios/TECNICO.md` a partir de `templates/relatorios/TECNICO.md`: achados agrupados
+por **tela** e **severidade**, cada um com o elemento afetado, o critério WCAG (quando houver) e a correção
+recomendada.
+
+## Passo 4 — Relatório para a gestão
+
+Grave `docs/trabalhos/<id>/relatorios/CLIENTE.md` a partir de `templates/relatorios/CLIENTE.md`: quais perfis de
+pessoas têm dificuldade, em quais tarefas, e as prioridades — **sem jargão técnico**.
+
+Registre os relatórios e o encerramento, e marque os dois como `final`:
+
+```bash
+npx @fontdata/ai-harness evento relatorio_gerado --trabalho <id> --nome auditar-ui --dados '{"caminho":"docs/trabalhos/<id>/relatorios/TECNICO.md"}'
+npx @fontdata/ai-harness evento relatorio_gerado --trabalho <id> --nome auditar-ui --dados '{"caminho":"docs/trabalhos/<id>/relatorios/CLIENTE.md"}'
+npx @fontdata/ai-harness evento trabalho_concluido --trabalho <id> --nome auditar-ui
+```
+
+## Passo 5 — Próximos passos
+
+Correções aprovadas seguem por `/nova-tarefa` (conjunto de melhorias) ou `/resolver-bug` (tela que não funciona),
+citando o id desta auditoria.

package/templates/skills/auditar-ui/references/lentes.md

@@ -0,0 +1,33 @@
+# Lentes da auditoria de interface
+
+## UX/UI
+
+- Clareza e consistência visual: componentes, espaçamentos, tipografia e cores iguais para a mesma função.
+- Hierarquia: a ação principal da tela é a mais evidente.
+- Feedback das ações: carregando, sucesso e erro sempre visíveis.
+- Estados de vazio, erro e carregamento tratados.
+- Fluxos confusos: passos desnecessários, rótulos ambíguos, ações destrutivas sem confirmação.
+- Responsividade nas larguras usadas pelo público da aplicação.
+
+## Acessibilidade (WCAG AA)
+
+| Verificação | Critério WCAG |
+|---|---|
+| Contraste de texto e de componentes | 1.4.3, 1.4.11 |
+| Texto alternativo em imagens | 1.1.1 |
+| Labels associados aos campos de formulário | 1.3.1, 3.3.2 |
+| Hierarquia de títulos | 1.3.1 |
+| Navegação por teclado e ordem de tabulação | 2.1.1, 2.4.3 |
+| Foco visível | 2.4.7 |
+| Foco preso e devolvido corretamente em modais | 2.4.3 |
+| Uso correto de ARIA e roles | 4.1.2 |
+| Mensagens de erro identificáveis e com sugestão | 3.3.1, 3.3.3 |
+
+## Severidade
+
+| Nível | Quando |
+|---|---|
+| **CRÍTICO** | Impede concluir uma tarefa (inclusive para quem usa teclado ou leitor de tela) |
+| **SÉRIO** | Conclui a tarefa com muita dificuldade ou erro frequente |
+| **MODERADO** | Atrapalha, mas há contorno simples |
+| **MENOR** | Inconsistência ou refinamento |

package/templates/skills/auditar-ui/templates/relatorios/CLIENTE.md

@@ -0,0 +1,26 @@
+---
+schema_versao: 1
+tipo: relatorio_cliente
+id: "{{id}}"
+trabalho_tipo: auditoria
+titulo: "{{titulo}}"
+status: rascunho
+criado_em: "{{data}}"
+atualizado_em: "{{data}}"
+arquivos: []
+---
+
+# {{titulo}}
+
+## Quem tem dificuldade hoje
+
+Perfis de pessoas e as tarefas em que elas travam ou erram.
+
+## Prioridades
+
+1. O que melhorar primeiro e para quem.
+2. Segunda prioridade.
+3. Terceira prioridade.
+
+## O que já está bom
+

package/templates/skills/auditar-ui/templates/relatorios/TECNICO.md

@@ -0,0 +1,31 @@
+---
+schema_versao: 1
+tipo: relatorio_tecnico
+id: "{{id}}"
+trabalho_tipo: auditoria
+titulo: "{{titulo}}"
+status: rascunho
+criado_em: "{{data}}"
+atualizado_em: "{{data}}"
+arquivos: []
+---
+
+# Auditoria de interface — {{titulo}}
+
+## Escopo
+
+Lente, URL auditada, perfil usado e telas percorridas.
+
+## Resumo por severidade
+
+| Crítico | Sério | Moderado | Menor |
+|---|---|---|---|
+| 0 | 0 | 0 | 0 |
+
+## Achados por tela
+
+### Nome da tela
+
+| Severidade | Elemento | Problema | Critério WCAG | Correção recomendada |
+|---|---|---|---|---|
+| | | | | |