Policy — 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: *e 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. *e passar:*prosseguir com o handoff e *ncluir a evidência*

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

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

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

5. *e 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)

• *eb 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.

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

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

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

  assert no status code e no shape do response.

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

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

• *uild artefato:*existir, ter tamanho razoável, abrir

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

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

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

• *18n string:*key resolve em todos os locales baseline; sem

  hardcoded leak.

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

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

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

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

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

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

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

• *11y de percepção real*(leitor de tela soa natural? contraste é

  legível *ra esta pessoa*) — ferramentas catalogam, humanos decidem.

• *udanç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).

• *onfirmaçã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:

• *hrome 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>.

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

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

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

  endpoint.

• *koderspecaudit`*para conformance de spec/policy.
• *k-test`*para suite TDDregressão completa de um módulo

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

• *laywright*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 *eploya*(§4 deploy-feedback) → *oda headless check*(esta policy) → *eporta 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.