Headless Self-Check Before User Handoff

Pedir avaliação humana sem ter verificado programaticamente o que era verificável é desperdício do tempo do usuário e da própria sessão. A regra é simples: se existe um caminho headless / programático para checar a mudança, Claude roda esse caminho antes de fazer o handoff e reporta o resultado.

Rules

1. Self-check antes do handoff

Antes de escrever ao usuário qualquer variante de "confere se ficou bom", "avalia aí", "me diz se passou", "abre essa URL e olha":

1. Identificar o caminho headless aplicável (ver §3).
2. Executá-lo.
3. Se passar: prosseguir com o handoff e incluir a evidência

   ("headless check passou: 200 OK no curl / screenshot anexo / kdiff zero / X tests green"). Pedir só a parcela subjetiva.

4. Se falhar: consertar e re-executar até passar (ou até concluir

   que a falha é fora do escopo). Nunca fazer handoff com headless vermelho sem dizer explicitamente "headless check vermelho, preciso da sua orientação porque motivo".

5. Se não há caminho headless aplicável: dizer explicitamente

   "não há check headless aplicável aqui — preciso da sua avaliação direta sobre X" antes do pedido, para que o usuário saiba que a ausência de evidência foi por falta de caminho automatizado, não por preguiça.

2. Aplica a (lista não-exaustiva)

• Web page já deployada: Chrome headless + screenshot + DOM

  assertion (document.querySelector(...) retornou nó esperado? computed style bate?). Quando o screenshot ajuda o handoff ("ficou centralizado?"), anexar ao chat.

• CLI/TUI: rodar o comando com fixture e capturar exit code +

  stdout/stderr. Diff contra output esperado quando aplicável.

• HTTP/gRPC endpoint: curl / grpcurl com payload de teste +

  assert no status code e no shape do response.

• SDK/biblioteca: smoke test no fixture do próprio repo

  (go test ./..., flutter test, cargo test --quiet).

• Build artefato: existir, ter tamanho razoável, abrir

  (tar tf, unzip -l, file), assinatura válida quando aplicável.

• Documento gerado (HTMLPDFSVG/PNG): parse não-erro, renderer

  não-erro, dimensions/áreas plausíveis.

• i18n string: key resolve em todos os locales baseline; sem

  hardcoded leak.

• CSS/style change: computed style do elemento alvo bate com a

  intenção (getComputedStyle(el).alignItems === 'center').

• Captura de telaáudio real (screenaudio capture): validável

  sem humano e sem o diálogo de consentimento do xdg-desktop-portal dirigindo org.gnome.Mutter.ScreenCast direto (API privilegiada do compositor sob o portal — cria um node PipeWire de screencast sem prompt na sessão GNOME/Wayland do próprio usuário; em CI use gnome-shell --headless --virtual-monitor). Assert: o consumidor de captura entrega frames (frames_sent ≈ fps×segundos). Harness canônico: engines/media/capture/test-harness/ (capture#033).

3. Não-aplica (handoff humano é o caminho certo)

• Julgamento estético subjetivo ("ficou bonito?", "a copy ficou

  natural?", "essa hierarquia visual transmite o que eu queria?").

• Gesture feel em mobile/desktop nativo (animação cosmética,

  haptic response, timing percebido) — só humano sente.

• A11y de percepção real (leitor de tela soa natural? contraste é

  legível pra esta pessoa?) — ferramentas catalogam, humanos decidem.

• Mudanças em ambiente isolado da sessão atual (env interno o

  usuário não abriu, device físico do usuário fora de alcance ADB).

• Confirmação de intenção quando a mudança é destrutiva ou

  irreversível — pedir confirmação humana é certo, headless check não substitui consentimento.

4. Ferramentas canônicas da Stack

Quando aplicável, preferir as ferramentas já presentes:

• Chrome headless (já instalado em todos os hosts de dev Koder)

  para web pages: google-chrome --headless --disable-gpu --screenshot=out.png --window-size=1280,800 <url>.

• chromedp (Go) para asserções DOM mais ricas — já vendored em

  tools/design-gen e tools/design-coverage.

• curl com -fsS -o /dev/null -w '%{http_code}\n' para smoke de

  endpoint.

• koder-spec-audit para conformance de spec/policy.
• /k-test para suite TDD/regressão completa de um módulo

  (rodar antes do handoff de mudança não-trivial).

• Capture harness (engines/media/capture/test-harness/) para

  validar captura de tela/áudio real sem humano: run_probe.sh <connector> <segundos> dirige o Mutter.ScreenCast + pw_video_probe e reporta frames_sent. Requer sessão GNOME/Wayland (real ou gnome-shell --headless --virtual-monitor no runner).

• Playwright apenas quando chromedp não couber — adicionar como

  dependência exige justificativa no PR.

5. Combinação com deploy-feedback.kmd §4

A §4 do deploy-feedback.kmd diz "publique sem perguntar"; esta policy diz "verifique sem perguntar". Combinadas: depois de uma edição visual em página já publicada, Claude deploya (§4 deploy-feedback) → roda headless check (esta policy) → reporta URL + evidência headless ao usuário em um único turno.

Why

Cada turno do usuário pra dizer "tá bom" ou "centraliza melhor" é um turno que não foi gasto avaliando o que só humano avalia. Quando a correção é mecânica (alinhamento bate? cor é esta? endpoint responde 200?), a IA tem todas as ferramentas pra confirmar — e poupar o humano dessa parcela é o trabalho do agente.

Anti-patterns

• "Deploy concluído, confere aí" sem rodar curl ou headless screenshot

  primeiro pra confirmar que a página não está 500.

• Pedir "olha se centralizou" sem ter verificado com

  getComputedStyle(...).textAlign ou screenshot.

• "Acho que ficou bom — me diz" quando há suite de testes do próprio

  módulo que ninguém rodou.

• Fazer handoff de CLI/build sem ter executado o binário pelo menos

  uma vez com --help--versionfixture mínima.

• Inferir que "deve estar OK" do diff sem executar.

Audit

koder-spec-audit policies headless-self-check (TODO — implementar quando houver corpus suficiente de logs de handoff): varre transcripts recentes em meta/context/handoff/recaps/ procurando pedidos de avaliação sem evidência headless quando houver caminho aplicável. Reporta como warning, não como error — judgement call.