- Município/território real fora do portfólio devolve lista vazia escopada (antes erro 'não reconhecido') + escopoRestrito: true declarado na resposta - Chips de município fora do acesso omitidos (nunca id pelado) - uniqueRelationshipIds canônico no lugar do uniqueIDs local - Chaves do input zod em inglês (scope/filter/mode); Salvador sem round-trip - Pledge query restrita a lideranças engajado + dica quando truncado + prompt
15 KiB
Impl: Sollinha — lideranças pendentes de abordagem + assessores responsáveis (gestão)
Status: aprovado Atualizado em: 2026-08-10 Issue: #524 Intenção: docs/plans/sollinha-liderancas-pendentes-abordagem.md Appetite restante: ~1 dia eng (herdado); sem migration / Consent / collection / UI nova
Registro de execução (2026-08-10)
- Entrega:
getPendingLeadershipsnova (src/utilities/ai/tools/getPendingLeaderships.ts) + registro noindex.ts+ seção no system prompt; 18 unit tests (tests/unit/pendingLeadershipsTool.unit.spec.ts); allowlist P3-D justificada. Mergeado via PR #547 (Closes #524); Issue fechadadone/in-prod. - Divergência da hipótese da intenção: nenhuma nos aceites. O corte de
negativo(fora do critério declarado) foi apresentado no gate humano e aprovado. Implementado como previsto: critério default fixo com eixo do compromisso = presença devotePledgeno escopo; recência/declaredAtdeixada para a B186. - Pós-merge, revisão /simplify (3 reviewers paralelos) — fixes aplicados em PR de follow-up:
- Escopo efetivo para assessor: município/território/cidade real fora do portfólio devolve lista vazia escopada (antes: erro "não reconhecido" — mentira de existência); resposta agora declara
escopoRestrito: truepara advisor (o plano prometia "a resposta declara o escopo efetivo" e o teste do shape vazio — ambos faltavam). - Chips de município fora do acesso: removidos (antes
{ id, nome: null }vazava o vínculo — mesma política da UIMunicipalityPortfolioCell). uniqueIDslocal substituído pelo canônicouniqueRelationshipIds(regra "edit the owner, don't twin").- Chaves do input zod em inglês (
scope/filter/mode— convenção de identificadores; valores continuam pt como dados). - Salvador: ramo da cidade antes do ramo de município (elimina o round-trip garantido de miss).
- Query de pledges restrita às lideranças
engajado(a_abordar/em_disputa nunca consultam o eixo) + guard de skip. dicade estreitar escopo quandotruncado+ linha no prompt sobreescopoRestrito/truncado.- Tipo nomeado
PendingLeadershipDocno lugar do cast inline.
- Escopo efetivo para assessor: município/território/cidade real fora do portfólio devolve lista vazia escopada (antes: erro "não reconhecido" — mentira de existência); resposta agora declara
exists: falseem hasManyadvisors: verificação obrigatória do plano executada ao vivo durante a revisão (reviewer 3, contra a DB local do worktree com linhas reais): o id-set do SQL bate com o filtro JS. Não pinado em int test (tools são unit-stubbed); risco residual zero observado.- Débitos deferidos (triage da revisão, sem Issue):
- Eixo do compromisso binário por liderança (não por liderança×município): liderança engajada com pledge em 1 de 3 municípios do escopo aparece/não aparece conforme o recorte da pergunta; o critério declarado torna isso transparente. Gatilho: se a família B185/B186/B189 precisar de granularidade por município, adicionar flags
semCompromissopor município na resposta. getLeaderships.SUPPORT_LABELS(duplicata privada desupportStatusLabels): gatilho: próxima edição degetLeaderships.- Mensagem "Escopo não reconhecido" para ZE individual ("Salvador ZE 3"): aceitável (intenção só promete nível cidade), texto permanece.
loadNamesByIdsao lado dos helpers P3-E (justificado: os P3-E usamoverrideAccess: true; aqui o acesso do ator deve valer). Polish.- Perda no main (fora desta entrega): o merge do C104 (PR #537) removeu do
docs/CHANGELOG-AGENTS.mdas entradas B183 e C102 — restauração é decisão de outra Issue (registrada no comentário da #524).
- Eixo do compromisso binário por liderança (não por liderança×município): liderança engajada com pledge em 1 de 3 municípios do escopo aparece/não aparece conforme o recorte da pergunta; o critério declarado torna isso transparente. Gatilho: se a família B185/B186/B189 precisar de granularidade por município, adicionar flags
Leitura da intenção
- Outcome: uma tool nova do Sollinha responde "quais lideranças ainda precisam ser abordadas" por território de identidade, cidade (Salvador = 19 ZE) ou município — com o critério de pendência declarado na resposta, responsáveis (assessores) à vista, links de navegação via
buildCampaignLinks, RBAC atual (assessor = portfólio; leader = deny fail-closed), filtro "sem assessor" (C3) e modo "municípios sem liderança" (C4). - O que NÃO negociar: leader lockdown (liderança não tem essa conversa — deny antes de qualquer query); assessor vê só o portfólio (RBAC atual via access control da collection); sem dados eleitorais na resposta; sem write tool; critério sempre visível; top N com total.
- O que reavaliar: a redação literal da semântica compartilhada ("status ≠
engajadoou semvotePledge") incluirianegativona lista — o aceite da intenção nomeia o eixo de status como "'a abordar'/'em disputa'", e produto não aborda quem é negativo. Corte desta engenharia:negativonunca entra (ver Decisões). Também reavaliado: a hipótese "fields: supportStatus/updatedAt/advisors, votePledge.declaredAt" — o eixo do compromisso é a presença devotePledge(leadership×municipality, unique), nãodeclaredAt; recência é semântica da B186, não desta.
Abordagem recomendada
flowchart LR
P[ai-chat route] --> B[buildAITools]
B --> T[getPendingLeaderships ctx]
T --> G[gate staff inline<br/>leader → { error }]
G --> S[resolve escopo<br/>município → cidade → região]
S --> Q1[find municipality<br/>região/cidade → ids]
S --> Q2[count+find leadership<br/>status in + escopo + sem_assessor]
Q2 --> Q3[find votePledge<br/>lideranças × escopo → set]
Q3 --> F[pendente = status≠engajado<br/>ou sem pledge]
F --> Q4[find campaignUser<br/>nomes dos assessores]
F --> R[{ escopo, criterio, total,<br/>liderancas, truncado }]
R --> L[buildCampaignLinks<br/>liderança/município/assessor]
Opções consideradas:
- A — Tool única
getPendingLeadershipscommodo(lideranças | municípios sem liderança) efiltro(sem assessor), escopo livre região|cidade|município. - B — Duas tools separadas (uma de lideranças pendentes, uma de municípios sem liderança).
- C — Estender
getLeadershipscom parâmetros de pendência.
Recomendação: A — a intenção foldou o C4 na mesma tool (decisão de produto já tomada: "mesma tool, mesma família de dado, aceite único 'saber o que falta no território'"); um modo discriminado mantém o surface enxuto (1 entrada no index, 1 descrição para o modelo) e o C4 é um modo de saída sobre o mesmo escopo. Rejeitadas: B (2 tools para o mesmo aceite; o modelo precisaria decidir qual chamar, e a resposta de C4 semânticamente "não tem liderança" é a mesma leitura de lacuna), C (mudaria o contrato da tool mais usada da família e o critério de pendência é default-ON, não um filtro opcional — poluiria as respostas de "quais lideranças temos em X").
Componentes / mudanças
getPendingLeaderships(src/utilities/ai/tools/getPendingLeaderships.ts, novo): factorytool()com input Zod; gate staff inline no topo doexecute(1 call site — regra 2=inline, 3+=extrair; não criar helper); resolução de escopo pura local (ordem: município → cidade Salvador → território, tolerante a acento); queries todasoverrideAccess: false, user: ctx.user(padrão da família — assessor auto-scope, semestimatedVotes).index.ts(src/utilities/ai/tools/index.ts): registrargetPendingLeaderships: getPendingLeaderships(ctx).systemPrompt.ts(src/utilities/ai/): seção curta "Lideranças pendentes" — quando usar a tool (perguntas de "o que falta abordar", "sem assessor", "municípios sem liderança"), obrigatório declarar o critério devolvido pela tool na resposta e oferecer links viabuildCampaignLinks(liderança por id, município por slug, assessor por id quando unrestricted).- Migration: sem migration.
- Access / Consent: nenhuma chave nova; gate fail-closed via
isStaffCampaignRole(ctx.user.role); leituras delegadas ao access control das collections (canReadLeadership/canReadVotePledge/canReadMunicipality/canReadCampaignUsers) — assessor portfólio, leader nem chega a query. - UI: Impeccable A — N/A (resposta em texto no chat existente; sem superfície nova).
Dados → forma
- Forma: lista em texto no chat (nome, municípios, status, última atualização, assessores) com total e truncamento top N — a intenção fixa "lista, não mapa; nunca % estadual; critério sempre visível". Rejeitadas: agregado por assessor na própria tool (o modelo agrupa pela lista — mesma leitura, sem modo de saída extra), estatística/percentuais (anti-goal).
Decisões de engenharia
- Critério de pendência.
pendente = status ∈ {a_abordar, em_disputa} OU (status = engajado E sem votePledge no escopo consultado). O eixo status é pré-filtrado nowhere(status: { in: [a_abordar, em_disputa, engajado] }) —negativoé excluído na query (fail-closed, não pode "vazar" por bug de JS). Compromisso = presença devotePledge(liderança×município, unique) com município no escopo; para escopo território/cidade, qualquer pledge dentro do escopo satisfaz o eixo (liderança tem compromisso no território). Critério declarado na resposta:'Status "A abordar" ou "Em disputa"; ou "Engajado" sem compromisso de votos no escopo consultado.'- Rejeitadas: (a)
declaredAtrecente no critério — recência é semântica da B186 (prioridades), que reusa a definição desta família; (b) exigir pledge em todos os municípios da liderança — para um território com 20 municípios isso tornaria quase toda liderança pendente e a resposta perderia a função de priorização; (c) incluirnegativo— contradiz o aceite (só a_abordar/em_disputa) e o significado operacional do status.
- Rejeitadas: (a)
- Gate. Inline na tool (1 call site):
if (!isStaffCampaignRole(ctx.user.role)) return { error: 'Leitura de dados de lideranças negada.' }. Rejeitada: extrair helper compartilhado estiloelectionDataGate(regra 2=inline/3+=extrair; nenhum outro domínio staff-only de gestão existe ainda). Mensagem no shape do chat da B180. - Resolução de escopo. Ordem: (1)
resolveMunicipalityName(aliases + acento, já canônico); (2)normalizeSearchPhrase('salvador')→ cidade (19 ZE viacity: { equals: 'Salvador' }); (3) território pornormalizeSearchPhrasesobrebahiaIdentityTerritories(ex.: "Vale do Jiquiriça" sem acento → 'Vale do Jiquiriçá'); (4) erro'Escopo não reconhecido: "X". Use um município, cidade ou território de identidade da Bahia.'Sem escopo → escopo do usuário (coordenador = estado; assessor = portfólio via access control). Rejeitada: deixar o Payload resolver comlike— não faz folding de acento e vazaria matches parciais. - Rótulos de status. Reuso de
supportStatusLabels(src/utilities/leadership/leadershipLabels.ts, fonte canônica da UI) — não doSUPPORT_LABELSlocal degetLeaderships.ts(duplicata existente; esta tool não a propaga). filtro: 'sem_assessor'(C3).advisors: { exists: false }nowhere(precedente do repo:revokedAt,readAt,municipality). Verificação obrigatória na implementação:exists: falseem hasMany (join table) — validar contra a DB local com query real; fallback documentado: fetch sem o filtro + filtro JS +countcom o mesmo where seria inconsistente, então o fallback real seria filtrar em JS e ajustartotalpelo conjunto filtrado (nunca usarcountcom where diferente do find).- Top N + total.
count+findcom o mesmowhere(sincronia garantida);limitdefault 20, max 50, sort-updatedAt(precedentegetLeaderships); resposta comtotaletruncado: true+ hint de estreitar escopo quando truncar. Adiado (barato): ordenação por "mais antigo primeiro" para pendentes — não muda aceite, revisitável com B186.
Fases verificáveis
- Tracer / server —
getPendingLeaderships.ts+ registro noindex.ts+ seção nosystemPrompt.ts+ unit tests novos (tests/unit/pendingLeadershipsTool.unit.spec.ts):- gate: leader →
{ error: 'Leitura de dados de lideranças negada.' }com payload stub intocado (fail-closed antes de qualquer query); coordinator/advisor passam; - critério: a_abordar sem pledge → incluída; em_disputa → incluída; engajado + pledge no escopo → excluída; engajado sem pledge → incluída; negativo nunca entra (assert no
wheredo stub:status in [a_abordar, em_disputa, engajado]); pledge fora do escopo não satisfaz o eixo; - escopo: "Vale do Jiquiriça" (sem acento) → where
region: 'Vale do Jiquiriçá'; "Salvador" → wherecity: 'Salvador'; município por nome; escopo inválido → mensagem de erro; - C3:
wherecontémadvisors: { exists: false }; - C4: municípios do escopo menos os cobertos por liderança (stub com docs de liderança multi-municípios); resposta declara o critério;
- assessores: nomes populados via segunda query
campaignUser(stub defindsequencial comvi.fn().mockResolvedValueOnce).
- gate: leader →
- Gates —
pnpm gate:fastna iteração; verificação local doexists: falseem hasMany; entrega compnpm push. - Docs — entrada curta em
docs/CHANGELOG-AGENTS.md+ este impl plan commitado.
Rabbit holes / Não escopo (engenharia)
- Não criar gate genérico HOF nem helper compartilhado (1 call site).
- Não mexer em
getLeaderships(incl. não "consertar" oSUPPORT_LABELSduplicado — fora do escopo, nota de simplify fica no triage). - Não tocar em
buildCampaignLinks/campaignNavigationUrls— os destinosleadership/municipality/advisor/municipalityList/leadershipListjá existem. - Não usar
declaredAt/recência no critério (B186), nemestimatedVotes(leader nunca vê; aqui nem aparece). - Sem paginação por offset (top N + escopo menor é o contrato da intenção); sem estatísticas/percentuais.
- Não mudar o shape
{ error }do chat nem o routeapi/ai-chat.
Riscos e mitigação
exists: falseem hasManyadvisors: pode não ser suportado como esperado — mitigado pela verificação local obrigatória na fase 1 (fallback JS documentado na Decisão 5).- Stub multi-call nos unit tests: tools fazem 3–5
payload.find/count— mitigado comvi.fn().mockResolvedValueOnceem sequência e asserts por chamada (index ou args do where). - Escopo de assessor fora do portfólio: perguntar por território que não administra devolve lista vazia/escopada (RBAC atual, fail-closed) — a resposta declara o escopo efetivo; teste com advisor + escopo fora cobre o shape vazio.
- Divergência de critério vs texto da intenção: o corte de
negativoé a única mudança de produto — apresentada neste gate antes de executar. - Flake
testDatabaseLease.int.spec.ts: fora de escopo (triage conhecido); reavaliar se recorrer.
Aceite de engenharia
- Aceite de produto da intenção coberto (perguntas de pendentes por região/cidade/município com critério declarado; assessores com link; C3; C4; RBAC atual; leader deny fail-closed)
- Invariantes AGENTS/engineering-standards (overrideAccess: false + user; copy pt-BR; identificadores em inglês; sem migration/Consent; top N com total)
- Testes previstos: unit (gate, critério, escopo tolerante a acento, C3, C4, nomes de assessores, where assert)