# HANDOFF — Sistema de Follow-up Inteligente > ⚠️ **INSTRUÇÃO PERMANENTE (não remover):** Este documento DEVE ser lido no > INÍCIO de toda sessão que trabalhe nesta feature, e ATUALIZADO + COMMITADO ao > final de CADA avanço (task concluída, decisão tomada, bug encontrado, bug > corrigido, teste rodado). Regra do Rafael: progresso só conta com PROVA > VISÍVEL (output de teste real, curl real, screenshot Playwright). Nada de > "implementado" sem evidência registrada aqui. Medidas de front-end são > verificadas por ferramenta (Playwright getBoundingClientRect/getComputedStyle), > nunca a olho. COMMITAR este arquivo a cada atualização — mudança só no > working tree se perde quando um subagent limpa a árvore (já aconteceu 1x). > **Sobre o diário abaixo:** as menções à Vercel são registro do dia em que cada > entrada foi escrita. O CRM é self-host em VPS, e o deploy que vale está em > [`docs/runbooks/deploy.md`](../../docs/runbooks/deploy.md). ## Contexto fixo - **Feature:** sistema de follow-up inteligente — grafo versionado + enrollment + relógio único; builder visual React Flow; fila UI; seletor no agente. - **Spec:** `docs/superpowers/specs/2026-07-21-followup-system-design.md` (aprovada pelo Rafael 2026-07-21). - **Plano:** `docs/superpowers/plans/2026-07-21-followup-system.md` — 8 ondas, critérios de aceite por onda. NENHUMA onda avança sem a anterior provada. - **Pesquisa (Fase 0):** `docs/research/followup-reference-mining.md` — padrões de odysseus/hermes/openclaw + autópsia do TomikCRM (as 3 causas-raiz: janela 24h ignorada no agendamento; ai_classify sem grace; pausas sem consumidor de retomada). - **Onde:** worktree `.claude/worktrees/followup`, branch `feat/followup-flows` (base `feat/operacao-visivel` @ 4408958). Checkout principal NÃO tocar. - **Método:** subagent-driven (implementer + reviewer por task), ledger em `.superpowers/sdd/progress.md`. Após CADA task: prova + atualizar+commitar este arquivo. - **Ambiente:** `.env.local` e `.e2e-creds.json` copiados do checkout principal. Testes de invariante: Postgres 17 efêmero do `baseline.sql` (`npm run test:invariants`). E2E: `npm run test:e2e` (creds do seed). - **Fundações que JÁ EXISTEM (não recriar):** `cron_jobs` + `job_queue` (kind `followup_turn`) da migration 0050; tool `schedule_followup` (`lib/agent-engine/agent/schedule-followup.ts`); handler `followup_turn` com re-entrada temporal (`lib/agent-engine/agent/followup-turn.ts`); before-send guardrails/pacing/STOP/`send_ledger`; `agent_inbox_items`; flywheel. O sistema novo ORQUESTRA essas peças. ## Estado atual - **Onda:** 5 ✅. Onda 6 ✅. Onda 7 ✅. Onda 8 EM ANDAMENTO: **Task 8.1 ✅ — gatilho de silêncio.** **Task 8.3 (jornada E2E) ✅ — `tests/e2e/followup-journey.spec.ts`, 2/2 rodadas verdes.** Ver Log de avanços. Falta na Onda 8: `stage_change` (não pedido nesta task — brief 8.1 focou só em `silence`), flywheel, e o restante da Task 8.3 (checklist DoD item a item + doc do PRD — o controller cobre essa parte separadamente). - **Task 7.1 ✅ — endpoint fila + aba + cancelar.** `GET /api/v1/ai/followups/queue` (viewer+): UNION app-side de `followup_enrollments` + `cron_jobs` (kind='at'+job_kind='followup_turn'), ordenado `(next_fire_at asc nulls last, id asc)`, cursor seek `{next_fire_at,id}` aplicado às 2 fontes, janela `limit+1` por fonte + merge (k-way lookahead — sem pular/duplicar entre páginas). `status`/`pointer_id` pulam a fonte de promessas (não têm esses campos); `q` resolve pra `contact_id`s primeiro, aplicado nas 2 fontes. `POST /api/v1/ai/followups/enrollments/:id/cancel` (manager+): 409 `already_terminal` se já encerrado, senão cancela + evento `cancelled_manual` + audit `followup_enrollment.cancelled` (ação nova). `app/app/ai/followups/page.tsx` virou `Tabs` (Fluxos/Fila) — o gate de página que exigia manager+ pra ver QUALQUER coisa foi relaxado pra só exigir org ativa (Fila é viewer+; Fluxos manteve seu próprio `canWrite`). `QueueTab.tsx` + `useFollowupQueue.ts` (useInfiniteQuery, mesmo padrão de `useAdminIncidents`) — filtros status/fluxo/busca (debounce 250ms), relativo+absoluto via `date-fns`/`ptBR` (reuso, sem dep nova), `AlertDialog` de cancelar. **PROVA AO VIVO (`tests/e2e/followup-queue.spec.ts`, 2/2 verde, `E2E_PORT=3010`):** setup 100% via API real (fluxo publicado, contato, enrollment) + `scripts/seed-e2e-followup-promise.ts` novo (mesmo padrão de `seed-e2e-queue.ts`, service role — não existe rota pública pra criar `cron_jobs`, só a tool do agente em runtime). Os 4 casos de aceite cobertos SEM DEFERIR NENHUM: (1) linha do enrollment com contato/fluxo/nó/próximo-disparo/status; (2) filtro status esconde e filtro por fluxo estreita pra exatamente 1 linha; (3) cancelar via dialog → some do filtro Ativo + toast + prova via API (`GET queue?status=cancelled` contém o id cancelado) + RBAC extra verificada ad-hoc (viewer faz POST direto em `/cancel` → 403 `forbidden_role` server-side, não só botão escondido); (4) busca por nome da promessa seedada estreita a fila INTEIRA da org pra exatamente 1 linha (`flow_name="Promessa"`, motivo, "Agendada", "em 3 dias", sem botão Cancelar). Screenshots em `test-results/followup-7.1-0{1..6}-*.png` — a 01 mostra dado 100% real incluindo 3 promessas de uso genuíno da IA já existentes no dev DB ("Prova Multimodal"). `npm run typecheck` 0, `npm run lint` 0 novo (2 erros pré-existentes intocados da Task 2.1), `npm run test:unit` 547/547 sem regressão. **Sem migration** (só leitura de tabelas já existentes; `cancelled_manual` é `event_type text` livre, sem CHECK a alterar). Detalhe completo em `.superpowers/sdd/task-7.1-report.md`. - **Task 6.3 ✅ — editor de condição de aresta.** `lib/followup/edge-condition-options.ts` (novo, puro): `edgeConditionOptions(sourceNode)` — `ai_classify` → `always` + 1 `class_match` por classe declarada + `class_match:no_reply`; `condition` → `always` + `cond_result:true/false`; qualquer outro tipo → só `always`. Mais `conditionKey`/`conditionLabel` (pt-br: classe crua, `no_reply`→"Sem resposta", `true`→"Sim", `false`→"Não", `always`→"Sempre") — 9 testes unit. `app/app/ai/followups/[id]/_components/EdgeConfigPanel.tsx` (novo): painel docado (mesmo estilo do NodeConfigPanel), mostra origem→destino e um Select com as opções exatas do nó de origem. `FlowCanvas.tsx`: `onEdgeClick` seleciona a aresta (fecha o painel de nó, e vice-versa — mutuamente exclusivos), `edgesForRender` (memo) injeta `label` derivado de `data.condition` em TODA aresta pro fio mostrar "positivo"/"Sem resposta"/"Sempre"/"Sim"/"Não" (React Flow's built-in edge label, sem edge customizado — confirmado no dist instalado que `BaseEdge`/`EdgeText` já suportam `label` nos 4 tipos default). `graph-mappers.ts`: só um `export` adicionado em `toFlowNode` (já existia, não exportada) — reuso, ZERO mudança de comportamento/round-trip. **PROVA (Playwright, `tests/e2e/followup-builder.spec.ts`, describe "Task 6.3"):** fluxo trigger→ai_classify(2 classes: positivo/objecao)→2 ações→2 fins (2 fins são necessários, não decorativos — `addEdge` do React Flow recusa uma 2ª aresta entre o mesmo par origem/destino, então `no_reply` e o fallback `always` do classify não podem mirar o MESMO nó "fim"). **Checagem negativa primeiro:** publica o grafo com TODAS as 4 arestas de saída do classify ainda `always` (estado pré-6.3) → 422 real, `Fluxo reprovado na validação`, nó do classify com anel vermelho + mensagem `"não tem edge class_match para a classe 'positivo'"`, exatamente 1 nó com erro (screenshot `followup-6.3-02-publish-422-all-always.png`). Depois abre cada aresta de saída do classify via o painel novo, seleciona `positivo`/`objecao`/`Sem resposta` (a `always` de fallback já vem certa, confirmada explicitamente no painel) → Publicar → SUCESSO: badge "Ativo", toast "Fluxo publicado.", zero erros no nó classify, e as 4 arestas mostram seus labels no fio (screenshot `followup-6.3-04-published-branching.png`) — o MESMO grafo que falhou acima agora publica porque o editor existe. Descoberta de implementação: o grid de posição default da paleta (220px de espaçamento < 224px de largura do card) sobrepõe cards com >4 nós e gera bezier loopy que esconde o label de aresta atrás de um card vizinho — o teste reposiciona os 6 nós manualmente (drag pelo header, fora dos handles Top/Bottom) num layout de árvore de verdade antes de conectar; e `fitView` do React Flow reajusta zoom (até 2x) a cada nó recém-medido, então o teste estabiliza via zoom-out ANTES de calcular posições-alvo (mesma cautela já documentada no teste 6.2). **PROVA:** 9/9 unit novos (`edge-condition-options.test.ts`), suíte unit completa 547/547, typecheck 0, lint 0 novo (os 2 erros pré-existentes em `graph-schema.test.ts` da Task 2.1 continuam intocados), `npm run build` OK, e2e `followup-builder.spec.ts` completo 7/7 (6.1+6.2+6.3, sem regressão). Sem migration nesta task. > ⚠️ **Esta linha descreve o mundo de 22/07 e ele mudou.** A W2-RAMOS trocou o menu por tipo de nó pelas SAÍDAS do nó (`nodeBranches`), e o conserto dos cartões (17/09) removeu `edgeConditionOptions` e o `edge-condition-options.test.ts` — o arquivo `lib/followup/edge-condition-options.ts` ficou só com `conditionKey`/`conditionLabel`. O rótulo da saída de escape de um nó ramificado também deixou de ser "Sempre" e virou "Outros casos". Para ver o que vale hoje: `rg -n "FALLBACK_(ALWAYS|OTHERS|NONE)_LABEL" lib/followup/graph-schema.ts`. - **RACE do classify lento — RESOLVIDA na 5.2.** `processNode` (node-handlers.ts) ganhou `wokeEarly?: boolean`: quando `waitElapsed=true` E `wokeEarly=true`, reenfileira classify em vez de rotear `no_reply`. `engine.ts` computa `wokeEarly` checando o marker `${node}:${steps}:wake` nos eventos do enrollment — gravado por `lib/followup/reactivity.ts` quando um inbound chega durante `waiting_reply` sem `cancel_on_reply`. Distinto do idempotency_key de passo que `waitElapsed` já checava (Task 5.1), então os dois sinais nunca se confundem. Provado em `tests/invariants/followup-reactivity.test.ts` (o TESTE CRÍTICO: 1º tick enfileira classify, reactivity empurra `next_eval_at` pra agora ANTES do grace vencer, 2º tick do engine real reenfileira classify — não roteia `no_reply`). - **Dev DB:** migrations 0054 e 0056 APLICADAS no projeto rrydmwnporysaiysiztn via Management API (token do CLI no keychain, entrada "Supabase CLI"/"access-token", formato go-keyring-base64). `database.types.ts` regenerado (public,storage,graphql_public). **0057 (Task 4.1, kind `followup_dead`) ainda NÃO aplicada no dev DB remoto** — não bloqueou a prova ao vivo da Task 4.2 porque o cenário provado (trigger→wait→condition→end) nunca passa pelo caminho `markDead`/`agent_inbox_items.kind='followup_dead'`; aplicar antes de qualquer prova futura que precise do caminho dead-letter. - **Migration seguinte livre:** 0058. - **Pendências deliberadas:** aplicar 0054 no dev DB remoto + regenerar `lib/database.types.ts` → fazer na preparação da Onda 3 (controller faz; subagents sem MCP Supabase). Minors do review 1.1 p/ triagem final: (1) idiom `duplicate_object` nas policies difere da convenção `drop policy if exists` do repo; (2) sem índice org-only em `followup_flow_versions`/`followup_enrollment_events`. ## Decisões tomadas - 2026-07-21: UM motor/UM relógio (`followup_enrollments.next_eval_at`); nós de IA via `job_queue`; envio at-most-once; validação de janela 24h no PUBLISH; grace obrigatório no classify; `paused_handoff` com retomada por evento. (Spec §2.) - 2026-07-21: `@xyflow/react` aprovado pelo Rafael para o canvas (dynamic import, medir bundle). - 2026-07-21 (Task 4.1): **`AdminClient` do engine NÃO é `SupabaseClient`** — é uma interface própria e estreita (poucos métodos nomeados: claim/loadGraph/loadLeadFacts/loadEvents/insertEvent/updateEnrollment/loadPointerName/insertDeadInbox). Motivo: `tests/invariants/**` roda contra Postgres cru (`pg.Pool`, sem PostgREST — `NEXT_PUBLIC_SUPABASE_URL` aponta pra porta inalcançável de propósito no `vitest.db.config.ts`), então um `AdminClient=SupabaseClient` real seria intestável ali. `lib/followup/engine.ts` exporta `createSupabaseAdminClient(admin)` pra produção (ainda sem consumidor — a rota de cron é task futura) e o teste DB implementa o adapter `pg`-puro inline. **Próximas tasks que precisarem de uma rota real usando o engine devem usar `createSupabaseAdminClient`, não reinventar.** ## Log de avanços (mais recente primeiro) - 2026-07-23: **Task 8.6 ✅ — furo anti-spam do Rafael fechado: 1 follow-up vivo por lead ORG-WIDE + pin do agente no enrollment.** **Migration 0062** (`20260722160000_0062_followup_enrollment_exclusivity.sql`) + apêndice idempotente no `baseline.sql` + linha no MANIFEST: (a) DEDUP FIRST via window function genérica — `(org, contact)` com >1 vivo (active/waiting_reply/paused_handoff) mantém o `started_at` mais recente e cancela o resto (`cancelled/exclusivity_backfill/next_eval_at null`) ANTES do índice (self-host-safe); (b) `idx_followup_enrollments_one_live` (MESMO nome, WHERE inalterado) de `(pointer_id, contact_id)` → `(organization_id, contact_id)`; (c) `agent_id uuid references ai_agents(id) on delete set null` + índice. **Gate refatorado** (`agent-followup-gate.ts`): 1 método `loadEnabledPublishedFollowupAgents` (uma query, deriva booleano+pick). `resolveAgentForAutomaticTrigger` → agent_id do agente que arma o pointer, **pick determinístico = MENOR uuid** quando >1 (documentado+testado). **silence-sweep** colapsa gate+pick no memo e pina `agent_id`; **manual-enroll** aceita `agent_id` opcional (valida org — nunca do body p/ tenancy) OU resolve do pointer. **Fila** (queue route + QueueTab + hook): embed `ai_agents:agent_id(name)` → `agent_name`, mostrado como subtexto "agente X" sob o fluxo; mapeamento extraído p/ `enrollmentToQueueRow` puro. **PERSONA-IN-SEND DEFERIDO (scoped follow-up, honesto):** a persona do envio vem de `loadPublishedAgentConfig(pool, org, channelSessionId)` — segue o NÚMERO (channel_session), não `agent_id`. Usar a persona PINADA exigiria mudar a assinatura de harness portado (`runAgentTurn`/`AgentTurnInput`/`loadPublishedAgentConfig`) + o enqueue do motor = cirurgia profunda que o brief mandou não fazer. O `agent_id` já fica PERSISTIDO no enrollment; o wire-up futuro é só no seam do turno, sem migration. Ressalva: número segue a conversa (continuidade preservada) e o agente pinado normalmente É o do número — divergência só com >1 agente armando o mesmo fluxo (raro no MVP). **PROVA:** `test:invariants` **2x verde** (40 files, 247 passed | 1 skipped, incl. baseline install `ON_ERROR_STOP=1` + update) — exclusividade **RED→GREEN** (índice antigo enrolla nos 2 fluxos = spam; o novo barra o 2º via 23505 org-wide), dedup 0062 (2 vivos → 1 + cancelled/ exclusivity_backfill), agent-pin (menor uuid). `test:unit` **564/564**, typecheck 0, lint 0 erros. **Consequência tratada+disclosed:** o índice virar org-wide quebrou o STOP test da reactivity (seedava 3 vivos p/ o MESMO contato — estado agora impossível por decisão do Rafael) → corrigido p/ 1 vivo (`paused_handoff`) + 1 terminal (`completed`), sob `DESKCOMM_GOV_INVARIANTS_EDIT=1`. **Pendente do controller:** aplicar 0062 no dev DB remoto + regenerar `database.types.ts`. Detalhe: `.superpowers/sdd/task-8.6-report.md`. - 2026-07-23: **Task 8.3 (jornada) — fix de review CRITICAL: try/finally cobria tarde demais.** O `try` original só abria DEPOIS do enrollment confirmado — mas o pointer vira elegível pro silence sweep quando o AGENT é publicado com `followup.enabled=true` (bem antes disso), então ~80 linhas (publish do agent, seed do contato, o loop de varredura) ficavam fora da proteção: uma falha ali deixava o pointer `active`+agent `published` órfãos, reabrindo o MESMO incidente do parágrafo anterior. Fix: `try` agora abre logo antes da seção 2 (criar/publicar o agent); `agentId`/`seed` viraram `let` fora do try (indefinidos até serem atribuídos); `finally` roda 4 passos INDEPENDENTES (disable do fluxo + `cleanup-flow-enrollments`, sempre; archive do agent se `agentId` existir; `cleanup-contact` se `seed?.contactId` existir), cada um no seu próprio try/catch — uma falha em cleanup-contact nunca impede o disable (o passo que realmente estanca o sweep). **Prova do fix**: throw injetado logo após o publish do agent (a linha exata onde a janela abre) → teste falhou como esperado → Postgres real confirmou o `finally` MESMO ASSIM desativou o pointer + arquivou o agent (0 pointers silence ativos, 0 enrollments vivos org-wide) → throw removido → 2 rodadas reais seguidas 1/1 verde cada → Postgres real limpo depois (0/0/0). Detalhe completo (throw + saídas coladas) em `.superpowers/sdd/task-8.3-report.md`, seção "Fix de review". - 2026-07-23: **Task 8.3 (jornada) ✅ — `tests/e2e/followup-journey.spec.ts`, a prova ponta-a-ponta que amarra o sistema inteiro: silêncio → enroll (gate do agente) → engine avança nó a nó → resposta do lead → classify roteia → outcome → fila.** **O seam de LLM (honestidade real-vs-injetado, explícito no arquivo e no report):** dev gateway não tem model ids reais utilizáveis — a spec NUNCA roda um agente de IA de verdade. Ela chama `completeTurnForEnrollment` (turn-bridge.ts) — a MESMA função que o worker 24/7 chamaria depois de uma chamada real de LLM — com resultado CONTROLADO (`{kind:'sent'}` no nó action, `{kind:'classified', class:'positivo'}` no ai_classify). TUDO o resto é real: build/publish/link do fluxo na UI, silence sweep gateado por agente publicado, engine avançando nó a nó via tick real do cron (`fn_claim_due_followup_ enrollments`), enqueue real em `job_queue`, roteamento de aresta, event_log real (`emit_event` + `event-log-drain`) acordando `reactivity.ts`, fila. **`scripts/e2e-followup-journey-helpers.ts` (novo)** — CLI de subcomandos (pg direto via `SUPABASE_DB_URL`, mesmo `createPgAdminClient` de produção que o worker 24/7 usa) cobrindo o que a API pública genuinamente não expõe: `seed-silent-contact` (contato+conversa com `last_inbound_at` no passado), `fast-forward-enrollment` (pula os 5min/15min reais de wait/grace sem dormir), `simulate-inbound` (insere `messages` + chama `emit_event('message.received', ...)` — a MESMA função que `lib/waha/ingest.ts` chama no webhook real), `complete-turn` (o seam acima), `find-job`/`get-enrollment`/`find-enrollment`/`list-events` (leitura de prova), `cleanup-contact`/`cleanup-flow-enrollments` (teardown). **Achado de UI real (não bypass):** `trigger_config` (kind='silence', threshold) não tem NENHUM controle no canvas do builder ainda — confirmado lendo `NodeConfigPanel.tsx` (o branch `trigger` só mostra texto explicativo). A spec seta via `PATCH /api/v1/ai/followup-flows/:id` — o MESMO endpoint que `handoff_policy` já usa no PublishBar, só sem widget dedicado ainda. Registrado como gap de UI conhecido, não escondido. **Achado operacional sério (2ª rodada, corrigido antes de fechar a task):** o gatilho de silêncio é CROSS-CONTATO por design (varre a org inteira) — uma 1ª tentativa que travou num timeout de teste (antes de eu ajustar `test.setTimeout`) deixou um fluxo de teste `active` sem cleanup, e ele começou a enrollar contatos REAIS do dev DB (`Rafael Melgaço`, `Cliente Fila E2E`, etc.) nas rodadas seguintes — 12 enrollments espúrios encontrados e removidos manualmente. Fix estrutural: (1) o teste desativa o pointer IMEDIATAMENTE após confirmar o próprio enrollment (não espera o fim do teste — desativar não afeta enrollments já vivos, só impede o sweep de pegar mais um), (2) todo o corpo pós-enroll roda em `try/finally` com `cleanup-flow-enrollments` (apaga TODO enrollment daquele pointer, não só o do contato desta run) — nunca deixa um pointer `active` ou um enrollment órfão se uma asserção falhar no meio, (3) as asserções de fila escopam por CONTATO+FLUXO (`.filter({hasText: flowName})`), não só contato, porque o mesmo contato pode aparecer em mais de um pointer de teste entre rodadas. **Fixtures de agente pra PUBLICAR (não só salvar draft):** `seed-e2e-followup-agent.ts` (Task 7.2) cria a credential SEM `validated_at` e a `channel_session` nasce `STARTING` — suficiente pra salvar rascunho, mas `fn_publish_ai_agent_version` exige `credential.validated_at is not null` e `channel_session.status='WORKING'`. `prepare-agent-fixtures` (novo subcomando) seta os dois via UPDATE direto antes do publish — não mexe no seed script original (mantém 7.2 intocado). **Grafo:** trigger→wait(fixed 5min, floor do schema — `duration_ms` mínimo é 300_000, não dá pra ir mais "pequeno")→action(ai_message)→ai_classify(1 classe "positivo", grace 15min — floor do schema)→3 fins (positivo/no_reply/always-fallback: `validateFlowForPublish` exige as 3 arestas de saída do classify — `missing_class_edge`/`missing_no_reply_edge`/`missing_always_fallback` — e o `addEdge` do React Flow recusa 2 arestas source→target iguais, então precisa de 3 nós de fim distintos, não 1). `steps_taken` esperado em cada marco documentado inline no spec (contagem exata: trigger-advance=1, wait-start=2, wait-elapsed=3, action-enqueue=4, classify-enqueue=6 — o `complete-turn('sent')` entre os dois soma +1 fora do tick). **PROVA — 2 rodadas seguidas, síncronas, 1/1 verde cada** (porta 3033, `E2E_PORT=3033`): rodada 1 = 1m18s, rodada 2 = 1m14s (timeout do teste elevado pra 300s via `test.setTimeout` — múltiplos round-trips reais de cron/drain, mesmo padrão de `webhooks.spec.ts`). Confirmado no Postgres real após CADA rodada: 0 enrollments órfãos, 0 contatos de teste remanescentes, pointer/agent desativados/arquivados. Screenshots em `e2e-artifacts/followup-8.3-0{1..4}-*.png` (fluxo publicado, seção Follow-up do agente, fila com o enrollment ativo, fila com o outcome "Concluído"). `npm run typecheck` 0, `npm run lint` 0 erros (117 warnings pré-existentes de `no-console`, mesma classe tolerada de todo `scripts/seed-e2e-*.ts`; nenhum novo além do padrão). **Sem migration nesta task** (só leitura/escrita via rotas e tabelas já existentes). Detalhe completo em `.superpowers/sdd/task-8.3-report.md`. **Pendente:** checklist DoD item a item, doc do PRD, HANDOFF final — o brief 8.3 divide essa parte pro controller (fora do escopo desta sessão). - 2026-07-22: **Task 8.1 ✅ — gatilho de SILÊNCIO (varredura TIME-DRIVEN no cron) + primeiro consumidor real do gate `isPointerEnabledForAutomaticTrigger`.** **Decisão de arquitetura (dada, não descoberta aqui):** silêncio é TIME-DRIVEN (varredura periódica), NÃO event-driven — não entra em `lib/followup/reactivity.ts` (que reage a `event_log`). Vive no cron `app/api/v1/cron/followup-flow-worker/route.ts`, que já roda a cada minuto com admin client: `runSilenceSweep` roda DEPOIS de `runFollowupTick` (e da sua auditoria), num try/catch ISOLADO — sweep falhando NUNCA aborta a resposta do tick (só loga, sem PII). **`lib/followup/silence-sweep.ts` (novo)** — `runSilenceSweep(deps)`: acha pointers `status='active'` com `trigger_config.kind='silence'` de TODAS as orgs (mesmo desenho cross-org de `fn_claim_due_followup_enrollments`) → GATEIA cada um via `isPointerEnabledForAutomaticTrigger` (memoizado por `orgId:pointerId` dentro da varredura) → acha contatos silenciosos da org → cria enrollment nascendo no nó `trigger` do grafo pinado, `next_eval_at=now`. Interface `SilenceSweepDb` estreita, mesma doutrina de `AdminClient`/ `ReactivityAdminClient`/`FollowupGateDb`; `createSupabaseSilenceSweepDb(admin)` é o adapter de produção. **"Última inbound" — achado central:** `conversations.last_inbound_at` JÁ EXISTIA (populado por `fn_ingest_message`, já usado por `workers/ai-response-worker.ts` e `lib/routing/queue.ts`) — **zero migration**. Ressalva real: é POR CONVERSA, o enrollment é POR CONTATO (um contato pode ter 2+ conversas/channel_sessions) — `loadSilentContactIds` busca todas as conversas da org com embed de contato (mesmo padrão 1:1 de `ai-response-worker.ts:255`) e reduz client-side pro `last_inbound_at` MAIS RECENTE por contato (Map). Decisão deliberada: NÃO criei uma function SQL pra fazer isso no Postgres (o `GROUP BY MAX` cabe numa reduction em memória pro volume do perfil PME do CLAUDE.md — evita migration+baseline+MANIFEST pra uma agregação pequena; troca é um refactor local se a escala pedir). **`segments`:** não havia NENHUMA primitiva de segmento de contato modelada (`enabled_segments` em `reentry-knobs.ts` é de outro sistema — Vendaval, valores opacos). Interpretei como overlap com `contacts.tags` (única coluna real, já com GIN index). Vazio/ausente = todos os contatos silenciosos — documentado como interpretação deferida no header do módulo. **Idempotência:** `insertEnrollment` é INSERT puro — 23505 (índice único `idx_followup_enrollments_one_live`) vira `skipped_existing`, nunca erro. Um contato que completou/cancelou pode re-enrollar na varredura seguinte se continuar silencioso — aceitável no MVP, sem cooldown table (fora de escopo por instrução explícita do brief). **`app/api/v1/cron/followup-flow-worker/route.ts`** — chama `runSilenceSweep` com `createSupabaseSilenceSweepDb(admin)` + `createSupabaseFollowupGateDb(admin)` depois do tick; audita `followup.silence_sweep_run` (nova action em `lib/audit/actions.ts`, union tipada) em sucesso. Response contract do tick (`ok(summary,...)`) INTOCADO — o sweep não polui o body de resposta, só audita separadamente — preserva `tests/api/followup-cron-worker.test.ts` sem precisar editá-lo. **PROVA (DB-real, `tests/invariants/followup-silence-sweep.test.ts`, 8 testes novos):** (1) pointer silence gateado + contato silencioso > threshold → 1 enrollment no nó trigger; 2ª varredura não duplica (unique-live); (2) gate-out em 2 sabores (sem agente publicado habilitando / agente publicado com `enabled=false`) → 0 enrollments — prova que o gate É chamado, não só importado; (3) boundary — silêncio < threshold → 0 enrollments, gate passou (isola o que bloqueou); (4) **gate SQL integration** (reviewer Minor #2 da Task 7.2 — requisito explícito desta task): `isPointerEnabledForAutomaticTrigger` contra `ai_agent_versions` REAL via adapter pg-backed espelhando a query de `createSupabaseFollowupGateDb` — publicado+enabled+membro→true, draft→false, enabled=false→false, cross-org→false. **Flake achado e corrigido na 1ª rodada** (mesma classe já documentada no fix da Task 5.2): `loadActiveSilencePointers` é cross-org de propósito, então um pointer `kind='silence'` de um `it` anterior (nunca desativado) contaminava `pointers_scanned`/`pointers_gated_out` do `it` seguinte — fix: `beforeEach` deletando `followup_flow_pointers where trigger_config->>'kind' = 'silence'` (escopo estreito, cascade via `on delete cascade`). **PROVA:** typecheck 0, lint 0 novo (os 2 erros pré-existentes de `graph-schema.test.ts`, Task 2.1, intocados), unit 551/551 sem regressão (nenhum unit novo — brief só pediu invariantes pra esta task). Invariantes: **3 rodadas seguidas, síncronas — 3/3 limpo**: 39/39 arquivos, 234 passed | 1 skipped em TODAS (era 226+1 antes — exatos +8, +1 arquivo, zero regressão). Detalhe completo em `.superpowers/sdd/task-8.1-report.md`. **Sem migration nesta task.** - 2026-07-22: **Task 7.2 ✅ — seletor de fluxo no editor do agente + gate de gatilho automático. Onda 7 fechada.** **Achado que muda o brief:** a config versionada de agente (`ai_agent_versions`) NÃO é um jsonb único — é coluna real por campo (`trigger_config`/`handoff_keywords` etc., confirmado lendo `supabase/baseline.sql` antes de codar). A suposição do brief ("aditivo, sem migration, é tudo jsonb") não batia; o campo novo precisou de **migration real**: `ai_agent_versions.followup jsonb not null default '{"enabled":false,"flow_pointer_ids":[]}'::jsonb`. Ainda assim aditivo — versões existentes nascem com o default, zero regressão em agentes que nunca falaram de follow-up. **Colisão de numeração real (multi-worktree):** `HANDOFF` dizia "migration seguinte livre: 0058", mas o dev DB remoto é COMPARTILHADO entre worktrees paralelos — outro branch já tinha aplicado `0058_media_multimodal`, `0059_agent_split_messages`, `0060_message_templates` (`supabase migration list` + Management API confirmaram; `information_schema.columns` já mostrava `multimodal_input`/`split_messages` em `ai_agent_versions` que meu `git log`/`ls supabase/migrations/` local não conheciam). Renumerado pra **0061** antes de aplicar — a lição: SEMPRE conferir o número livre contra o REMOTO (`supabase migration list` ou a Management API), não só contra `ls supabase/migrations/` local, quando o dev DB é compartilhado entre worktrees. `fn_ai_agent_version_content_immutable()` (0051) re-assentada (`create or replace`, forward-fix idempotente) incluindo `followup` no veto de mutação de versão PUBLICADA — sem isso o campo ficaria mutável por fora do contrato de imutabilidade que o resto da tabela já respeita (achado ao ler a trigger antes de mexer no schema). **Aplicação sem MCP:** as tools `mcp__plugin_supabase_supabase__*` não estavam carregadas nesta sessão. `SUPABASE_DB_URL` (pooler, role `agent_worker`) não tem ownership pra DDL (`must be owner of table ai_agent_versions`) — aplicado via Management API (`POST /v1/projects/:ref/database/query`) com o access token do keychain (`security find-generic-password -s "Supabase CLI" -a "access-token" -w`, decodificado de `go-keyring-base64:`), mesmo mecanismo que o CLI usa. Achado extra: a API da Management exige `User-Agent` ou o Cloudflare WAF devolve 403 (`error code: 1010`) sem explicar — resolvido com `User-Agent: supabase-cli/2.95.4`. Migration re-aplicada 2x (idempotência provada) antes de seguir. `lib/database.types.ts`: regen completo via `supabase gen types` traria TAMBÉM as tabelas/colunas de OUTROS worktrees (`multimodal_input`, `split_messages`, `message_templates`...) — fora do escopo desta task e do meu branch. Optei por um patch cirúrgico manual (só `followup: Json` nos 3 shapes de `ai_agent_versions`), impacto mínimo, sem misturar schema alheio no diff. **Zod:** `followupConfigSchema` (`{enabled: boolean.default(false), flow_pointer_ids: uuid[].max(20).default([])}`) em `lib/ai/agents/validation.ts`, campo `followup` em `versionShapeSchema` — aditivo confirmado pelos 551/551 unit (era 547/547 na Task 7.1) sem quebrar nenhum teste de agente existente. **UI:** `app/app/ai/agents/[id]/_components/FollowupFlowPicker.tsx` (novo) — multi-select que ESPELHA `ToolPicker.tsx` (fieldset+checkbox, mesmo padrão visual Sage), filtra `useFollowupFlows()` client-side pra `status==='active'` (a rota `GET /api/v1/ai/followup-flows` não tem `?status=` — checado, fora do escopo mínimo mudar a rota), empty-state linka pra `/app/ai/followups`. `AgentForm.tsx` ganha a seção "Follow-up" depois de "Handoff humano": `Switch` pro `followup.enabled` + o picker pro `flow_pointer_ids`. `VersionDiff.tsx` ganha uma seção "Follow-up" (pills de fluxo adicionado/removido + enabled A→B) — nice-to-have barato pra não deixar o diff de versão cego a este campo novo. **Gate (onda 8 ainda não existe):** `lib/followup/agent-followup-gate.ts` (novo) — `isPointerEnabledForAutomaticTrigger(db, orgId, pointerId)`: um gatilho AUTOMÁTICO (silence/stage_change/ conversation_end) só pode enrollar nesse pointer se algum agente PUBLICADO da org tiver `followup.enabled=true` e `followup.flow_pointer_ids` incluir o pointer. Enrollment MANUAL (`POST /api/v1/ai/followups/enrollments`) NÃO passa por este gate (escolha explícita de humano). Confirmei por grep que NENHUM código cria enrollment a partir de gatilho automático ainda (silence/stage — só a Task 4.2 tem enrollment manual; o worker de tick AVANÇA enrollments existentes, não os CRIA) — então o gate nasce exportado + testado (4 unit tests, `agent-followup-gate.test.ts`) SEM CONSUMIDOR. **A Task 8.1 (silence/stage → enrollment) DEVE chamar esta função antes de inserir a linha em `followup_enrollments` — não reinventar.** Interface estreita (`FollowupGateDb`) + adapter de produção (`createSupabaseFollowupGateDb`), mesma doutrina de `AdminClient`/`ReactivityAdminClient`. **PROVA AO VIVO (Playwright headed, `tests/e2e/followup-builder.spec.ts`, describe "Task 7.2", `E2E_PORT=3010`, 2 rodadas seguidas 1/1 verde + suíte completa do arquivo+queue 10/10 verde):** setup 100% via API como **ADMIN** (não manager — achado ao ler `page.tsx`: manager VÊ o form mas `readOnly=true`, só admin salva; login com MFA TOTP real via `.e2e-creds.json → admin_totp`) — publica um fluxo mínimo trigger→end, cria um `mcp_agent`+v1 draft via `POST /api/v1/ai/agents` usando fixtures novas (`scripts/seed-e2e-followup-agent.ts` — credential+channel_session, únicas coisas que faltavam pra criar um agent via API; não existiam no repo). Abre `/app/ai/agents/:id`, prova o default aditivo (`version.followup === {enabled:false, flow_pointer_ids:[]}` na criação), habilita o toggle + marca o checkbox do fluxo publicado (locators, não screenshot-only), screenshot `e2e-artifacts/followup-7.2-01-flow-selected.png`, clica "Salvar rascunho", screenshot `e2e-artifacts/followup-7.2-02-saved.png`, e prova via **API** (`GET .../versions/:vid`) que `followup.enabled===true` e `flow_pointer_ids` contém o id do fluxo — persistência real, não só estado de UI. Cleanup arquiva o agent + desativa o fluxo. **Bug pré-existente encontrado e corrigido (fora do escopo do brief, mas achado rodando a suíte completa):** o teste RBAC da Task 6.1 (`viewer não vê o botão de criar fluxo`) ficou órfão desde o commit 6546271 (Task 7.1, já commitado antes desta sessão) — a página `/app/ai/followups` deixou de redirecionar viewer pro `/403` (decisão deliberada: Fila é viewer+), mas a asserção velha (`waitForURL(/\/403/)`) nunca foi atualizada e falhava 100% das vezes isolado (não era flake de servidor — reproduzido 2x limpo). Corrigido pra refletir o RBAC atual: página carrega, botão "Novo fluxo" ausente. Regra do CLAUDE.md ("CI vermelho é pra ser consertado, não reportado de volta") — consertado, não só relatado. **PROVA (unit/typecheck/lint):** `npm run typecheck` 0, `npm run lint` 0 erros novos (os 2 pré-existentes de `graph-schema.test.ts` da Task 2.1 continuam intocados; +2 warnings `no-console` do novo script de seed — mesmo padrão tolerado de TODOS os outros `scripts/seed-e2e-*.ts`), `npm run test:unit` **551/551** (+4 sobre a Task 7.1: `agent-followup-gate.test.ts`). Migration 0061 aplicada no dev DB remoto + reaplicada 2x (idempotência provada) + `database.types.ts` atualizado (patch cirúrgico). Detalhe completo em `.superpowers/sdd/task-7.2-report.md`. - 2026-07-22: **Task 6.2 ✅ (commits e06bf1e/bb928fd/fbc2415/6fdce2d/3d5d9f4) — builder visual completo em `/app/ai/followups/[id]`, o centerpiece da feature.** 5 incrementos, cada um provado por Playwright antes do próximo: 1. `lib/followup/graph-mappers.ts` — `toReactFlow`/`fromReactFlow` puros (sem DB), round-trip provado (7 testes: 6 tipos de nó + 3 condições de aresta + posições não-triviais + piso de 2 nós). `graphsEqual` (sorted-key stringify) alimenta o dirty-state do incremento 5. 2. `page.tsx` (gate manager+, 404 fora da org) + `FlowBuilder.tsx` (shell `next/dynamic ssr:false` — `@xyflow/react` só carrega nesta rota) + `FlowCanvas.tsx` + `NodePalette.tsx` (clique OU HTML5 drag-and-drop via `screenToFlowPosition`). GET `/api/v1/ai/followup-flows/:id` ganhou `versions_count`/`previous_version_id` (2ª query de linhagem, sem `.limit()` de propósito — o fake DB de `tests/api/followup-flows.test.ts` não suporta esse método). 3. 6 node cards (`Trigger/Wait/Condition/Classify/Action/End`Node.tsx) finos sobre `NodeCard.tsx` compartilhado — ícone+cor Sage distintos por tipo (trigger=accent, wait=info, condition=warning, ai_classify=accent sólido, action=success, end=error), subtítulo derivado do config via `describeNodeConfig`. `onConnect` sempre cria aresta `{type:'always'}` (editável só por convenção de default — sem UI de edge ainda, decisão de escopo: a spec de aceite não exercita `ai_classify`/`condition` com múltiplas saídas). 4. `NodeConfigPanel.tsx` — 1 form por tipo, cada campo valida contra o schema exportado de `graph-schema.ts` (`safeParse`) antes de escrever no nó vivo; inválido = erro inline, nunca propaga estado parcial. **Achado de design importante**: a 1ª versão usava `Sheet` (Radix Dialog) e o overlay full-screen bloqueava clique em OUTRO nó do canvas (pointer-events da camada, independe de `modal={false}`) — trocado por `