Skill: screen-verify

Você vai autenticar e navegar a aplicação do projeto em ambiente local de desenvolvimento para verificar uma tela — o gate screenVerify. Dados de acesso: keelson.local.json (abaixo); o que verificar: o roteiro (um HANDOFF-*.md ou o pedido do Diretor).

Fronteira de segurança (não-negociável): só ambiente local. Dados locais são fictícios — logar localmente é seguro. Nunca aplique nada desta skill contra produção, nem com conta real de usuário.

Dados de acesso: keelson.local.json (LOCAL, não-versionado)

As credenciais e a URL de teste vêm do keelson.local.json na raiz do projeto — arquivo gitignored, criado pelo /keelson:init. Um realm por área logada da aplicação (ex.: admin, portal); chaves: screenVerify.realms.<nome>.{baseUrl, login: {path, username, password}} + screenVerify.defaultRealm — o arquivo real é lido em runtime.

• Formato flat (sem realms) → ver Legado, no fim deste arquivo.
• Arquivo ausente ou campo em branco → não invente credenciais nem URL. Peça ao Diretor que rode /keelson:init (ou preencha o keelson.local.json), e não declare a verificação feita. "Não tenho as credenciais" nunca vira "está ok".
• Nunca ecoe a senha em log, relatório, screenshot de terminal ou mensagem. Use-a só no preenchimento do campo de login.
• Leitura do arquivo negada pela plataforma (permissão do projeto ou do harness) é permissao_ambiente (decisão 4.133): registre a negativa literal e siga a rota do §8.1 do handoff-protocol.md — o Diretor executa ou autoriza. Ler o arquivo por outro canal (shell, cat) é contorno, nunca saída.

Seleção do realm

O realm alvo vem do item do roteiro (campo Realm do HANDOFF-*.md) ou do pedido do Diretor. Na falta de indicação: realm único → use-o; vários → case a rota alvo com a baseUrl mais específica que a contenha. Rota que não casa com nenhum realm → pergunte ao Diretor; nunca chute credencial — logar com a conta errada mascara bug em vez de revelar.

Isolamento por realm (não-negociável)

• Credencial do realm X entra só no formulário de login do realm X.
• Um realm por vez, com o browser fechado entre eles (browser_close): abas do mesmo contexto compartilham cookies, então "aba própria" não isola nada. Reaproveitar a sessão de um realm (ex.: admin) para verificar tela de outro (ex.: portal) mascara exatamente os bugs de autorização/isolamento que esta verificação existe para pegar.
• Item negativo cross-realm (ex.: "com a sessão do portal, acessar rota admin → esperado: negado") é roteiro legítimo — e é a única exceção: execute-o dentro da sessão do realm de origem, sem fechar o browser antes.

Ferramentas: Playwright MCP

Dirija o navegador só com as ferramentas do Playwright MCP (mcp__playwright__*) — não use mcp__Claude_Browser__*, claude-in-chrome nem computer-use (Bash continua válido para setup de ambiente/banco do projeto). As ferramentas MCP chegam deferred: carregue-as antes de usar.

Servidor ausente ou sem resposta → isso é indisponibilidade de runtime de browser, não "ambiente sem tela" genérico: siga o diagnóstico nomeado da sondagem (${CLAUDE_PLUGIN_ROOT}/docs/_meta/conventions/handoff-protocol.md, §8.1) e diga o comando exato de instalação. Não caia para outro browser em silêncio — método único é decisão de projeto (decisão 4.49).

O modo do browser (headless por padrão), o navegador e o diretório de saída vivem na configuração do servidor (.mcp.json do projeto ou escopo do usuário), escrita pelo /keelson:init — não são ajustáveis em runtime. Precisa ver a janela para investigar? Isso é reconfiguração, não improviso: rode /keelson:init de novo (ou tire o --headless do .mcp.json) e diga isso ao Diretor.

Divisão com a suíte E2E (quality.e2e — decisão 4.166)

Projeto com quality.e2e na ficha tem specs E2E versionados como memória desta verificação: comportamento que já tem spec se prova rodando o recorte (<quality.e2e> --grep "@AC-NNN-XXX"), sem browser dirigido. Esta skill entra no comportamento novo (ainda sem spec) e no julgamento que asserção não captura — layout, tema, estado visual. O que você verificar e aprovar aqui é insumo para o developer codificar em spec na própria task (régua: ${CLAUDE_PLUGIN_ROOT}/guidelines/core/TESTING.md, "Specs E2E"); os artefatos de execução continuam nas pastas gitignored abaixo, e imagem nunca vira asserção commitada.

1. Subir/abrir o ambiente

Suba/abra a app pelo método do projeto (ver guidelines/project/ e a ficha). Se o server já está de pé, não suba nada — navegue direto (browser_navigate) para a baseUrl do realm alvo. Sem sessão, a app cai na tela de login. Nenhum server rodando → suba pelo método do projeto e só então navegue.

Identidade do código se prova, não se presume (decisão 4.30): antes de confiar em qualquer evidência, prove que o processo serve o código sob teste — path raiz do server, SHA/marcador exposto, ou o efeito de uma mudança já commitada na branch.

Estabilidade é o segundo eixo da identidade (decisão 4.276): capture git rev-parse HEAD + git status --porcelain na raiz servida ao iniciar o roteiro e re-capture ao fechar — mudança surgida durante o exercício em arquivo do escopo verificado é trabalho concorrente: pare e escale com o par de capturas como evidência (verificação sob árvore mudando não é reprodutível). O estado pré-existente — o diff não-commitado sob verificação — é a linha de base declarada, nunca achado.

2. Login

Tire um browser_snapshot da tela de login (é ele que dá os ref dos campos), preencha usuário e senha com os valores de login do realm alvo via browser_fill_form (havendo "lembrar de mim", marque — prolonga a sessão), submeta e confirme que saiu da rota de login. A sessão (cookie httpOnly) persiste no contexto; navegue então à tela alvo (<baseUrl><rota>). Roteiro com mais de um realm → conclua um realm, browser_close, e recomece o login no próximo, respeitando o isolamento acima.

A credencial entra só por browser_fill_form/browser_type no campo do formulário. browser_evaluate e browser_run_code devolvem o código inteiro no output — credencial dentro deles é log (guidelines/core/SECURITY.md, Security Logging & Alerting Failures, decisão 4.236), mesmo quando o script "só preenche o campo".

3. Executar o roteiro (o que verificar)

Chegando à tela com dados reais, escolha os passos relevantes:

• Erros de console (browser_console_messages, level: "error") e logs do server — runtime/build quebrados (escopo por navegação: ver Armadilhas).
• Chamadas de rede (browser_network_requests, filter por rota de API) — APIs que falharam; browser_network_request traz o corpo quando importar.
• Texto e estrutura (browser_snapshot) — KPIs, listas, badges, estados vazios, presença/ausência de item. O snapshot de acessibilidade é mais confiável que o screenshot para conferir conteúdo, e é o que dá os ref para interagir.
• JS na página (browser_evaluate) para valores de CSS concretos (cor, dark mode, espaçamento) — mais confiável que screenshot para cor/fonte.
• Interação real (browser_click, browser_type, browser_select_option) reconfirmando o estado depois; browser_wait_for em vez de presumir que já renderizou.
• Viewport mobile/tablet e tema escuro (browser_resize) — responsivo e dark mode.
• Screenshot (browser_take_screenshot) como prova visual final.
• Comparação com referência visual (linha ## Referência visual do roteiro — decisão 4.203): capture a referência fora da sessão autenticada — antes do login, ou depois de browser_close (mesma mecânica do isolamento por realm acima); a referência é material de leitura, nunca alvo de login, e origem externa bloqueada por --allowed-origins não é bug da app. Salve a captura na pasta de artefatos ao lado do screenshot da tela e julgue em binário — alcança / não alcança, cada diferença nomeada. Como todo artefato daqui, o par de imagens é conveniência: a prova durável é o texto do julgamento.

Registre a evidência item a item. Ao fechar um HANDOFF-*.md, grave a evidência no próprio doc (✅/❌).

Artefatos: thoughts/screen-verify/<slug>/<chave-da-sessão>/

Screenshot, dump de console e dump de rede são gravados em arquivo, na pasta de artefatos do gate — gates.screenVerify.artifactsDir da ficha (default thoughts/screen-verify), que é o --output-dir do servidor. thoughts/ é gitignored: esses arquivos são material transitório para o desenvolvedor, nunca vão para o git.

• Caminho relativo, agrupado por slug e sessão (decisão 4.330): obtenha a chave da sessão uma vez — bash "${CLAUDE_PLUGIN_ROOT}/scripts/session-dir.sh" <raiz> session-key --create --slug <slug> — e passe filename nas chamadas: "<slug>/<chave>/<PLAN-MMM|yyyy-mm-dd-descrição>/<item>-<o-que-é>.png" (ex.: "professional-portal/20260901-101530-a1b2c3d4/PLAN-003/V1-dashboard-vazio.png"). Chave vazia (sem id de sessão) → omita o nível da sessão (padrão legado) e declare isso no report. Nome falante, não o page-{timestamp} default. browser_console_messages e browser_network_requests aceitam filename do mesmo jeito — use quando o dump for longo demais para o report. A subpasta da sessão é o espelho que o session-dir.sh gc lista e remove junto com a casa da sessão; HANDOFF Pendente que cite a chave segura o espelho.
• Registre o caminho que a ferramenta devolveu, não o que você pediu: se o servidor estiver com outro --output-dir, o arquivo caiu em outro lugar e o report tem que dizer onde (.playwright-mcp/ — ver Armadilhas).
• O arquivo nunca é a prova. A prova durável é o texto: o que foi observado, no HANDOFF e no INDEX. O artefato é conveniência local — um clone limpo não o tem, e a verificação precisa continuar de pé sem ele (decisões 4.26/4.46).
• Screenshot de tela logada pode conter dado de dev: nunca capture a tela com o campo de senha preenchido e visível.

Armadilhas (cheque ANTES de diagnosticar "bug")

Sintomas de ambiente que imitam bug de UI:

• Estado de transição se confere no DOM (posição/opacity computados via browser_evaluate), não no screenshot — a captura pode pegar o meio da animação. Use browser_wait_for para o estado estável antes de capturar.
• Viewport implícito: sem browser_resize, você mede no tamanho default do servidor (--viewport-size), que pode não ser o que o roteiro assume. Dimensione explicitamente antes de qualquer afirmação sobre layout ou breakpoint.
• Console e rede são por navegação por padrão: browser_console_messages sem all: true e browser_network_requests mostram o que veio desde a última navegação — um erro de boot desaparece depois que você navegou para outra rota. Colete antes de sair da tela, ou peça all: true.
• Recurso externo bloqueado (fonte, CDN) por --allowed-origins/--blocked-origins na config do servidor aparece como falha visual da app. Antes de abrir bug de estilo, cheque a rede: requisição bloqueada não é bug do código.
• Arquivo em .playwright-mcp/ é o sinal de que o servidor está sem --output-dir (é o diretório default dele) — reporte como config divergente (/keelson:init conserta), porque essa pasta pode não estar coberta pelo .gitignore do projeto.

Um sintoma desses só vira bug depois de re-medido com o estado estável e o viewport são.

4. Regras de segurança (não-negociáveis)

Além da fronteira local-only e do sigilo da senha (acima): alterar permissões/senha, mesmo em dev, é mudança sensível — faça o mínimo para destravar a verificação e diga ao Diretor o que alterou. Detalhes de ambiente/domínio (subir serviços, fixtures, pegadinhas de autorização) vivem em guidelines/project/ — consulte-os quando o setup ou uma tela gated exigir.

Legado: formato flat do keelson.local.json

baseUrl + login direto sob screenVerify, sem realms, segue válido em runtime: equivale a um único realm implícito (a seleção e o isolamento por realm acima valem para ele como realm único). O /keelson:init migra o arquivo para realms preservando os valores.