[FEAT] lib/slack.ts e /api/cron/iris-watchdog com as três checagens

[cpenaforte-clickbus]

User story

Como o time, eu quero ser avisado no Slack quando um repositório fica sem análise ou um ciclo não
roda, para não descobrir pela ausência de dado no dashboard semanas depois.

Acceptance criteria

lib/slack.ts

• Envio por incoming webhook, canal fixo, no padrão do RocketBus/clickbus-os-editor
• Variável SLACK_WEBHOOK_URL
• Sem webhook configurado → modo mock: loga o payload e não envia
• Envio condicionado a VERCEL_ENV === "production" — não NODE_ENV, que também é production
  em deployment de preview e faria o canal receber alerta de preview

/api/cron/iris-watchdog

• 0 */3 * * * por Vercel Cron, uma linha de crons no vercel.json
• Autenticada pelo CRON_SECRET existente, mesmo padrão da /api/cron/sync-integrations
• Checagem 1 — repositório defasado: last_refs_digest do censo difere do refs_digest da última
  análise, e essa análise é mais velha que o threshold. A comparação é por digest, não por
  last_pushed_at — medido, em 19 de 50 repositórios a data está adiante do último evento de branch,
  o que daria 38% de alerta a mais. O last_pushed_at entra como a idade que a mensagem mostra.
• Checagem 2 — ciclo que não rodou: nenhuma linha nova em analysis_runs na janela esperada. É a
  checagem que transforma silêncio em alerta, qualquer que seja a causa.
• Checagem 3 — ingestão do worker sem a chave: nenhuma linha nova com refs_digest na janela.
  Por presença da chave, não por ausência: enquanto o agente local estiver ligado, digest nulo é o
  normal das linhas dele.
• Uma mensagem por execução, agregando as três checagens, e nenhuma quando não há nada errado
• Todo achado vai também para o log da rota, que é o piso se o webhook falhar
• Threshold de partida 30 horas (um tique perdido dá 24 h de defasagem), configurável

O que o watchdog não faz

Não dispara o worker. Despachar de fora exigiria actions:write na plataforma e daria dois lugares
para olhar quando quebrasse. Ele observa o resultado no banco — se a análise não está lá, para o
watchdog o ciclo não aconteceu, qualquer que tenha sido o motivo. É a única peça do design cujo
funcionamento não depende do worker estar de pé.

Sobre a cadência

Não precisa ser mais fina: a detecção é threshold mais cadência, então de 1 h para 3 h o pior caso vai
de 31 h para 33 h sobre um threshold de 30 — e o que se detecta é atraso, nunca perda. Em troca, a
cadência mais grossa divide por três a repetição do alerta: 8 avisos por dia em vez de 24, enquanto a
condição persistir. Se o threshold baixar, a regra que segue valendo é cadência de no máximo um
quinto do threshold.

Bloqueado por

As colunas de censo: #225.

Se encaixa em qual estágio?

Stage 2 — mesmo mecanismo e mesmo padrão da /api/cron/sync-integrations que já está no ar. Nenhum
agendador novo e nenhuma integração nova além do webhook.

Links

• DD 0010 §3.6 e §5: https://github.com/RocketBus/clickbus-rfc-design-docs/blob/main/design-docs/DD0010-Coleta-Centralizada-de-Atribuicao-do-Iris.md
• Parte de: Fase 4 — Watchdog e censo da organização #211

Se a repetição do alerta incomodar

Enquanto uma condição persistir, a mensagem repete a cada tique do cron — 8 avisos por dia com a
cadência de 3 h. O passo seguinte, só se a operação pedir, é guardar o last_alert_at da checagem:
estado pequeno, e deliberadamente fora desta entrega.

A plataforma já manda e-mail por Resend (platform/lib/email.ts), então somar ou trocar canal é mudar
uma função — nada no design depende do canal ser o Slack.

Quando cada checagem passa a produzir sinal

As checagens 2 e 3 funcionam desde o merge: leem só analysis_runs. A checagem 1 compara censo
contra análise, então só produz sinal quando o ciclo estiver publicando o censo
(#222) — antes disso ela não tem o que comparar e fica silenciosa, que é o comportamento
correto e não um bug. Isso é deliberado: censo velho, ou ausente, não cega o watchdog, porque é a
checagem 2 que transforma silêncio em alerta.