docs(plan): C158 + C159 — Sollinha no acervo de falas e na comunicação

Registra os planos aprovados no gate de 2026-09-14: tool do Sollinha para sugerir trechos do acervo de falas (C158) e chat escopado ao acervo para a assessoria de comunicação (C159, depende de C158).

Related #982
Related #983

docs/plans/sollinha-acervo-falas-trechos.md

@@ -0,0 +1,78 @@
+# Sollinha: sugerir trechos de falas do acervo para vídeos
+
+Status: plano — registrado (blocked até plano em main)
+Atualizado em: 2026-09-14
+Issue: #982
+Priority: P1
+Impeccable: A — N/A (resposta em texto/markdown no chat existente; sem superfície nova)
+Rascunho UI: N/A — sem UI
+Appetite: ~1 dia eng; uma tool read-only nova + orientação no prompt + testes; sem migration/collection/Consent
+Responsável: —
+
+## Intenção
+
+O acervo de falas do deputado já está em produção (C153/C154/C155), mas achar o trecho certo para uma peça continua sendo garimpo manual: buscar, abrir o vídeo e caçar a minutagem. Quem produz conteúdo já conversa com o Sollinha para outras tarefas — e agora quer perguntar em linguagem natural ("qual uma boa fala para um reels sobre o hospital do subúrbio?") e receber trechos candidatos prontos para levar à edição. Falta a ponte entre a pergunta e o acervo.
+
+## Persona e fluxo
+
+- **Persona / contexto:** quem produz conteúdo da campanha (coordenação/candidatura hoje; assessoria de comunicação via C159, item irmão), sob prazo curto de peça, com o chat do Sollinha aberto no sheet/drawer.
+- **Job principal:** converter um tema em 1–3 trechos de fala do deputado, com citação aproximada e minutagem, para montar o vídeo sem garimpar o acervo na mão.
+- **Fluxo desejado:** pergunta o tema ("hospital do subúrbio") → o Sollinha busca no acervo → devolve as sugestões com trecho citado e minutagem de começo/fim → o usuário abre o acervo no ponto do trecho, assiste e baixa.
+- **Anti-goals de produto:** não é editor de vídeo nem entrega arquivo; não lê a fala inteira no chat; não inventa fala nem minutagem; não vira busca semântica; não expõe o acervo fora de `/campanha`.
+
+## Objetivo e aceite
+
+- A pergunta de exemplo ("Qual seria uma boa fala do deputado para criarmos um reels sobre o hospital do subúrbio?") devolve 1–3 sugestões, cada uma com citação aproximada do trecho e minutagem de começo e fim.
+- Cada sugestão leva ao acervo no ponto do trecho (onde já há assistir/baixar/abrir a fonte); o chat não entrega arquivo nem edita.
+- **Guardrails:** sem trecho encontrado, o Sollinha diz que não achou — nunca inventa fala ou minutagem; cada sugestão é um trecho contínuo, curto o bastante para virar peça; quem não lê o acervo recebe negativa clara (fail-closed), nunca dado parcial nem erro técnico; a citação vem do ASR e pode ter ruído — vale como localizador, a referência é o vídeo; sem migration/collection/Consent.
+
+## Dados (intenção)
+
+- **Vou apresentar dados?** Sim, superfície neste item — o consumidor é o usuário no chat; a resposta é a superfície.
+- **Decisões desbloqueadas:** quem edita escolhe qual fala vira peça e já sabe o ponto de corte, em vez de procurar o trecho no acervo.
+- **Forma:** _adiada ao plano de implementação_ — restrições de produto: trecho contínuo com começo e fim; citação aproximada + minutagem; poucas sugestões por resposta; nada de transcrição inteira nem métrica de acervo.
+
+## Dados da decisão (literais)
+
+- N/A — nenhum valor fixo de dados a preservar: a faixa de sugestões e o formato do link são comportamento de resposta, detalhados no plano de implementação (sem tabela, ID, env ou string exata de produto).
+
+## Direção no codebase (hipótese)
+
+- **Áreas prováveis:** `src/utilities/ai/tools/` (tool nova + registro em `index.ts`) e `src/utilities/ai/systemPrompt.ts`; reuso da busca existente do acervo em `src/utilities/speech/` (`speechListFilters.ts`, `speechViewModels.ts`, `speechPageData.ts`) e do normalizador `src/lib/speechSearch.ts`.
+- **Precedente a olhar:** tools de leitura atuais (factory por contexto que consulta com o usuário da sessão); gate de negação por papel de B180; retorno com critério/escopoRestrito/truncado de B185; links do chat de B162/B187/B188/B198; testes de lockdown por tool e int do acervo (`tests/unit/electionToolsLockdown.unit.spec.ts`, `tests/int/speechAcervo.int.spec.ts`).
+- **Risco de acoplamento:** leader lockdown intocado e advisor segue negado no acervo; o gate da tool deve espelhar quem tem leitura do acervo (o communicator incluído) — o gate de staff não cobre esse recorte. Os segmentos ASR são frasais e o acervo hoje destaca UM segmento; juntar trechos contíguos com começo/fim é justamente o trabalho novo deste item.
+
+## Dependências
+
+- Entregues (duras, satisfeitas): C153 (catálogo `speech`/`speechSegment`), C154 (vertical Comunicação + busca no acervo), C155 (backfill; 997 discursos em produção).
+- C159 (chat para a assessoria de comunicação — #983) depende deste item, não o contrário: a tool nasce com o gate do acervo para que C159 a herde.
+- Nenhuma dependência dura bloqueante.
+
+## Fora de escopo
+
+- Ler a fala inteira / transcrição completa no chat — a íntegra fica no detalhe do acervo.
+- Cortar, editar ou gerar vídeo, e baixar arquivo pelo chat — o acervo já oferece assistir/baixar/abrir a fonte.
+- Busca semântica/embeddings — a busca textual do acervo é a base (item futuro se houver demanda).
+- TTS, narração, legendas e curadoria de trechos/favoritos/listas editoriais.
+- Exposição pública do acervo e mudanças de UI no acervo (C154) além do reuso.
+
+## Rabbit holes de produto
+
+- **Busca semântica/embeddings.** Se alguém "só completar": índice vetorial, sinônimos, reranking, infra nova. **Corte neste item:** busca textual existente; sem resultado, o Sollinha diz que não achou.
+- **Ler a fala inteira no chat.** Se alguém "só completar": transcrição longa na resposta, contexto estourado, citação sem foco. **Corte neste item:** só trechos contínuos curtos com começo/fim; a íntegra fica no acervo.
+- **Cortar/editar/gerar vídeo.** Se alguém "só completar": editor, fila de render, storage. **Corte neste item:** o chat sugere e aponta; edição é ferramenta externa.
+- **Publicar o acervo fora de `/campanha`.** Se alguém "só completar": página pública, compartilhamento externo, direitos. **Corte neste item:** acervo segue interno.
+
+## Questões em aberto (produto)
+
+- **Quem usa nesta entrega?** **Opções:** A) só quem já tem o chat (coordenação/candidatura) | B) a assessoria de comunicação também, via C159. **Decisão do gate (2026-09-14): B** — a assessoria de comunicação também usa, via C159 (item irmão, dependente desta tool), sem bloquear esta entrega.
+- **O link na resposta aponta para onde?** **Opções:** A) acervo interno no trecho (`?t=`), que já dá assistir/baixar | B) também URL direta do VOD/YouTube. **Decisão do gate (2026-09-14): A** — o trecho sugerido aponta para o acervo interno no ponto do trecho; a fonte direta só quando o detalhe do acervo não bastar.
+- **Quantos trechos e quão longos?** **Opções:** A) sempre 1 | B) 1–3 conforme o pedido | C) até N com janela fixa. **Decisão do gate (2026-09-14): B** — 1–3 trechos conforme o pedido, trecho contínuo curto o bastante para peça; a política fina de janela fica no plano de implementação.
+
+## Referências
+
+- GitHub Issue: #982
+- Rascunho UI (gate): N/A — sem UI
+- Planos irmãos: [`sollinha-tool-urls-navegacao.md`](sollinha-tool-urls-navegacao.md) (B162 — links no chat), [`sollinha-tools-eleitorais-leader-lockdown.md`](sollinha-tools-eleitorais-leader-lockdown.md) (B180 — gate fail-closed), [`sollinha-liderancas-pendentes-abordagem.md`](sollinha-liderancas-pendentes-abordagem.md) (B185 — retorno com critério), [`acervo-videos-comunicacao.md`](acervo-videos-comunicacao.md) (C154 — acervo e RBAC), [`catalogo-falas-solla.md`](catalogo-falas-solla.md) (C153), [`backfill-acervo-falas.md`](backfill-acervo-falas.md) (C155).
+- Arquivos-chave: `src/app/(campaign)/campanha/api/ai-chat/route.ts`, `src/utilities/ai/`, `src/utilities/speech/`, `src/lib/campaignRoles.ts`.
+- `AGENTS.md` — rotas `/campanha`, leader lockdown e RBAC.

docs/plans/sollinha-para-comunicacao.md

@@ -0,0 +1,79 @@
+# Sollinha na assessoria de comunicação (chat escopado ao acervo)
+
+Status: plano — registrado (blocked até plano em main)
+Atualizado em: 2026-09-14
+Issue: #983
+Priority: P2
+Impeccable: A — N/A (as superfícies do chat já existem; habilitadas por papel, sem design novo)
+Rascunho UI: N/A — sem UI
+Appetite: ~0,5–1 dia eng; habilitar a superfície do Sollinha para o `communicator` com escopo de tools, orientação de prompt e testes; sem migration, collection ou Consent
+Responsável: —
+
+## Intenção
+
+A assessoria de comunicação é quem produz os vídeos e reels da campanha — e é quem mais precisa garimpar falas do Solla. Hoje ela não tem Sollinha: desde o C154 todas as superfícies do assistente são escondidas do papel `communicator`, decisão deliberada daquela entrega. Com o C158, o Sollinha passa a saber pesquisar o acervo de falas e sugerir trechos; sem este item, justamente a persona que precisa disso não consegue abrir o chat.
+
+Este item reabre aquela decisão de forma estreita: o `communicator` ganha o Sollinha, mas escopado ao acervo — as demais tools negam com mensagem clara, sem vazar dados de campanha nem estourar erro técnico.
+
+## Persona e fluxo
+
+- **Persona / contexto:** assessoria de comunicação (jornalista/videomaker) dentro da vertical `/campanha/comunicacao`, com prazo curto de produção, alternando entre a busca do Acervo e o chat.
+- **Job principal:** pedir uma fala para uma peça em linguagem natural e receber trechos do acervo para levar ao corte.
+- **Fluxo desejado:** entra na vertical → abre o Sollinha → pergunta "o que o Solla já falou sobre Farmácia Popular?" → recebe trechos com contexto e link para o Acervo → pergunta algo fora do escopo ("quantos votos tivemos em Ilhéus?") → lê uma negativa clara e educada, sem erro técnico.
+- **Anti-goals de produto:** não é assistente geral da campanha; não vê dados de campanha, eleitorais ou de municípios; não substitui a busca do Acervo (a superfície principal segue sendo o C154); não vira copiloto de pauta, agenda ou demandas.
+
+## Objetivo e aceite
+
+- O `communicator` vê e abre o Sollinha na vertical (FAB, drawer e botão do header), como qualquer outro papel habilitado.
+- Uma pergunta de acervo (ex.: a pergunta-exemplo do C158) responde com trechos de falas e caminho para o Acervo — a primeira prova de valor.
+- Pergunta fora do escopo recebe negativa clara e educada — nunca erro técnico, nunca dado de campanha, eleitoral ou de município.
+- Os chips de abertura do `communicator` são perguntas de acervo, respondíveis com as tools dele.
+- **Guardrails:** leader lockdown intocado; `advisor` inalterado (segue sem acervo e sem mudança no chat); nav do `communicator` intacta (só Comunicação); rate limit e limites atuais de conversa valem igual.
+
+## Dados (intenção)
+
+- **Vou apresentar dados?** Não — o item é acesso/superfície. Quem apresenta os trechos é a tool do C158, dentro do chat que já existe.
+- **Decisões desbloqueadas:** nenhuma nova — escolher qual fala cortar já é do fluxo C154/C158.
+- **Forma:** _adiada ao plano de implementação_ — sem restrição de produto nova neste item.
+
+## Dados da decisão (literais)
+
+- N/A — nenhum valor fixo de dados. O escopo deriva dos predicados de papel já existentes (`canReadSpeechCatalog` e `canUseCampaignAssistant`, em `src/lib/campaignRoles.ts`); sem tabelas, thresholds ou envs novos.
+
+## Direção no codebase (hipótese)
+
+- **Áreas prováveis:** o predicado de superfície em `src/lib/campaignRoles.ts:34` e seus dois consumidores no shell (`src/components/campaign/shell/ai/CampaignAISidebarShell.tsx:45`, `src/components/campaign/shell/CampaignDesktopHeader.tsx:29`); o prompt global `src/utilities/ai/systemPrompt.ts` (sem regra para `communicator` hoje); a montagem de tools (`src/utilities/ai/tools/index.ts`) e a rota `src/app/(campaign)/campanha/api/ai-chat/route.ts` (só auth + rate limit, sem filtro de papel); os chips em `src/lib/sollinhaOpeningQuestions.ts:45-50`; e `src/utilities/ai/campaignNavigationUrls.ts` (links negados com erro claro).
+- **Precedente a olhar:** C154 (escondeu o chat deste papel — este item reabre), C158 (tool de busca no acervo, dependência dura), B180 (`docs/plans/sollinha-tools-eleitorais-leader-lockdown.md`) e B185 (`docs/plans/sollinha-liderancas-pendentes-abordagem.md`), além do access do acervo do C153.
+- **Risco de acoplamento:** lockdown do leader e negativa do `advisor` no acervo não podem regredir; o `communicator` não ganha municípios nem dados eleitorais; `maxDuration = 60` e o rate limit de 50 msg/15 min seguem iguais.
+
+## Dependências
+
+- **C158** (dura, #982) — a tool de busca no acervo; sem ela o chat do `communicator` responde pouca coisa útil.
+- C153, C154 e C155 entregues (acervo no banco, vertical e busca).
+
+## Fora de escopo
+
+- Abrir o acervo (ou o chat pleno) para `advisor`/`leader` — decisão C153 mantida; sucessor só com nova evidência.
+- Assistente de pauta, agenda ou demandas da comunicação — item futuro, sem ID.
+- Chat do Sollinha no site público ou fora da vertical — não.
+- Novas tools além do escopo de acervo; redesign do drawer ou da persona.
+
+## Rabbit holes de produto
+
+- **"Já que abriu, vira assistente completo da comunicação."** Se alguém "só completar": pauta, agenda, demandas, clipping. **Corte neste item:** só acervo no escopo; o resto nega.
+- **"Aproveita e abre o acervo para o advisor/leader."** Se alguém "só completar": muda a decisão C153 de escopo de leitura. **Corte neste item:** decisão mantida; ninguém novo entra.
+- **"Refaz o prompt/persona do zero para o communicator."** Se alguém "só completar": reescrita global do prompt e das superfícies. **Corte neste item:** orientação de escopo pontual no prompt, sem design novo.
+
+## Questões em aberto (produto)
+
+- **Qual o escopo de tools do `communicator`?** **Opções:** A | só a tool do acervo + o mínimo (calculadora e links do que ele acessa), e as demais negam claramente; B | assistente completo com gate por tool. **Decisão do gate (2026-09-14): A** — escopo mínimo; o valor está no acervo.
+- **Tools que hoje lançam `Forbidden` ou devolvem vazio devem passar a responder negativa clara?** **Opções:** A | sim, sempre negativa clara em linguagem de produto, com ajuste pontual nos donos das tools; B | manter como está. **Decisão do gate (2026-09-14): A** — a resposta ao `communicator` nunca pode virar erro técnico.
+- **Chips de abertura do `communicator`?** **Opções:** A | curadoria própria de perguntas de acervo, por capacidade real (padrão B191/C154); B | reaproveitar o conjunto do leader. **Decisão do gate (2026-09-14): A** — chips de acervo que ele consegue responder de verdade.
+
+## Referências
+
+- GitHub Issue: #983
+- Rascunho UI (gate): N/A — sem UI
+- Planos: `docs/plans/acervo-videos-comunicacao.md` (C154), `docs/plans/catalogo-falas-solla.md` (C153), `docs/plans/sollinha-tools-eleitorais-leader-lockdown.md` (B180), `docs/plans/sollinha-liderancas-pendentes-abordagem.md` (B185); C158 #982 (tool de busca no acervo).
+- Pistas de teste: `tests/unit/campaignNav.unit.spec.ts:65-71`, `tests/unit/campaignSollinhaOpeningQuestions.unit.spec.ts:20-51`, `tests/int/speechCatalog.int.spec.ts:123-155`, `tests/e2e/campaignSpeechAcervo.e2e.spec.ts:70-107`, `tests/e2e/campaignAiChatOpeningChips.e2e.spec.ts:103` e o mock `mockSollinhaChat` em `tests/e2e/fixtures/campaignE2EFixtures.ts:604-612`.
+- `AGENTS.md` — convenções de papel/access e o registro da decisão C154.