Tela /construtor · Construtor ISP

26.0 · Por que este capítulo existe (abertura conceitual)

Quando o Anexo F desenhou a arquitetura institucional e o Anexo G consolidou o SOP do Comitê, um vão operacional permaneceu: como uma pessoa, sentada diante de uma tela, transforma um dossiê de ideias em uma tese de Investimento Social Privado tecnicamente defensável? Sem essa ponte, todo o aparato institucional (atas, endossos, modos bloqueante/advisory) opera sobre objetos produzidos fora do sistema — em planilhas pessoais, documentos de e-mail, slides soltos —, o que reintroduz silenciosamente os três custos invisíveis discutidos no Capítulo 1: opacidade do raciocínio, irreprodutibilidade dos pressupostos e intransferibilidade institucional do conhecimento.

O Construtor ISP é a resposta a esse vão. É um wizard estruturado em seis etapas alinhadas 1:1 ao capítulo 3 do Guia ISP 2026 (foco e materialidade · diagnóstico territorial · modelo e instrumento · due diligence de OSCs · métricas, avaliação e M&A · engajamento e transparência), com um score de aderência calculado em tempo real, snapshots imutáveis para auditoria e um caminho formal de promoção: isp_drafts → teses_isp. A escolha pelo wizard não é cosmética: a literatura sobre checklist manifestos (Gawande, 2009) mostra que a redução do espaço de decisão a passos discretos, com critérios explícitos de avanço, é o método mais barato e mais robusto de elevar a qualidade média de decisões complexas em ambientes de alta variabilidade — exatamente o caso da filantropia estratégica brasileira.

26.1 · Anatomia da tela

A rota /construtor comporta dois modos de visualização. O dashboard (rota raiz) lista rascunhos e templates; o wizard (rota /construtor/$draftId) é a tela de trabalho propriamente dita. Memorize as cinco zonas do wizard — elas governam tudo o que segue.

26.2 · As seis etapas, uma a uma

Cada etapa endereça um requisito explícito do Guia ISP 2026. A ordem é recomendada, não vinculante: o operador pode pular etapas e voltar a elas — mas a aderência por etapa só sobe quando os campos canônicos estão preenchidos.

A soma dos pesos é Σwᵢ = 1,00 — mesma propriedade aritmética do Score Consolidado da tela /score (Cap. 8). A escolha por uma forma aditiva sobre uma forma multiplicativa repete o argumento técnico do Capítulo 8: aditividade preserva interpretabilidade marginal e tolera ausência parcial de informação sem zerar o composto.

26.3 · O Copiloto IA · papel e limites

A zona D (cf. Fig. 26.1) hospeda o Copiloto ISP, uma ponte com a Lovable AI Gateway que oferece dois serviços por etapa: sugestões (gera rascunho de campo a partir do contexto já preenchido) e críticas (lê os campos atuais e aponta lacunas, riscos epistemológicos e incongruências com o Guia ISP). O modelo padrão é google/gemini-2.5-pro, com fallback para gemini-2.5-flash em janelas de baixa cota.

26.4 · Snapshots, comparador e auditoria

Cada draft pode produzir versões imutáveis chamadas snapshots. Um snapshot é uma cópia completa do estado do rascunho num instante T, persistida em isp_draft_snapshots com versão incremental e rótulo livre. Há dois caminhos para criar snapshot:

• Manual — botão Novo snapshot no painel de finalização. Usado pelo operador para travar uma versão exploratória antes de mexer em algo arriscado.
• Automático — disparado pela função promoverParaTese no instante da promoção. O rótulo é Promovida v{n} e a versão é selada para auditoria. Esse snapshot é o artefato que o Conselho lê quando precisa reconstruir por que aquela tese tem aquela formulação.

26.5 · Cross-link com o restante do agente

O Construtor não é uma ilha. Cada draft pode estar vinculado a três objetos do resto do sistema, e essas pontes são bidirecionais.

O cross-link Tese ↔ Draft usa um marcador textual construtor_draft_id:<uuid> em teses_isp.observacao. A tela /teses extrai o UUID e renderiza um badge “Construtor” que retorna ao wizard original. Essa opção arquitetural — anotar a origem como metadado textual em vez de criar uma coluna FK — preserva a independência das duas tabelas para casos em que a tese é editada manualmente após promoção.

26.6 · Promoção a Tese · ato governamental

O botão Promover a tese é o único ponto da tela que cria registros em outras tabelas do sistema. É, em sentido institucional, o equivalente do tornar vigente da tela /score: um ato com efeito governamental, não apenas analítico.

26.7 · Templates · acelerador institucional

O dashboard do Construtor lista templates públicos (tabela isp_templates com publico = true) que pré-preenchem os campos das etapas 1 e 2. A v1.0 do agente entrega três templates curados (Educação antirracista, Saúde materna negra, Empreendedorismo de territórios negros), que materializam linhas históricas de atuação do Instituto. A migração mais recente adicionou UNIQUE em isp_templates.slug, eliminando risco de duplicação por race condition.

26.8 · Erros comuns e como evitá-los

• Tratar o Construtor como editor de texto: escrever três parágrafos no campo justificativa da etapa 1 sem preencher tema, público e território faz a aderência da etapa parar em ~30% — campos estruturados pesam mais que prosa livre, deliberadamente.
• Pular a etapa 4 (DD das OSCs) presumindo que “será feito depois”: a etapa pesa 20% e a ausência derruba a aderência consolidada para baixo de 60, bloqueando a promoção mesmo com as outras cinco etapas completas.
• Aceitar sugestões do Copiloto sem revisar: ver §26.3. Texto aceito do modelo entra na tese promovida e fica em ata — o ônus epistêmico permanece no operador.
• Promover sem snapshot manual prévio: a promoção cria snapshot automático, mas somente da versão promovida. Se você queria comparar com a versão de “antes da revisão final”, precisava ter feito o snapshot manual antes — não há undo.
• Confundir promoção com vigência: promover cria a tese em status rascunho; vigente exige tramitação no Comitê (Anexo G, §G.3). Operadores apressados anunciam internamente “tese aprovada” quando a tese mal saiu do Construtor.

26.9 · Lendo o painel de aderência por etapa

A barra superior do wizard mostra um indicador colorido por etapa:

• Verde (≥ 80%): etapa robusta; preenchimento canônico completo.
• Âmbar (50%–79%): etapa funcional mas com lacunas; revisar antes da promoção.
• Vermelho (< 50%): etapa frágil; a aderência consolidada vai sofrer fortemente.

A leitura agregada (consolidada) aparece no painel de finalização. Não confundir as duas leituras: uma etapa em verde não garante aderência consolidada verde, pois o peso da etapa pode ser baixo.

26.10 · Exportação · PDF executivo, Markdown, JSON

O painel de finalização oferece três caminhos de exportação:

• PDF executivo — gerado por server function dedicada com pdf-lib (Worker-compatible). Inclui capa, score consolidado, breakdown por etapa, conteúdo das seis etapas e rodapé institucional. É o artefato canônico para anexo em ata e envio ao Comitê.
• Markdown executivo — versão texto formatada para colagem em atas e e-mails internos.
• JSON completo — payload bruto com dados, score e por_etapa. Útil para análise externa, backup ou diff manual entre versões.

26.11 · Mapeamento ao Guia ISP 2026 (rastreabilidade formal)

Esta seção existe para auditoria externa: documenta, etapa por etapa, qual seção do Guia de ISP para os mercados financeiro, de seguros e de capitais (ANBIMA · B3 · CNseg · Febraban, fev/2026) o Construtor materializa.

26.12 · Estado atual do subsistema (v1.0) e roadmap

O Construtor ISP foi entregue em quatro sprints e dois ciclos de polimento. O que está em produção:

• Wizard de seis etapas com auto-save, navegação não-linear e score em tempo real.
• Copiloto IA com sugestões e críticas (não-streaming).
• Snapshots manuais e automáticos; comparador snapshot vs. atual.
• Cross-link bidirecional Draft ↔ DAG, Draft ↔ Alocação, Draft ↔ Tese.
• Promoção a Tese com inserção em teses_isp e badge no Construtor.
• Exportação em PDF executivo, Markdown e JSON.
• Três templates públicos curados; UNIQUE(slug) garantido.

O que está pendente, em ordem de prioridade declarada:

1. Streaming do Copiloto via SSE token-by-token.
2. Validador formal ANBIMA mapeando 1:1 os 26 critérios formais com breakdown por critério.
3. UI de templates privados por usuário/conselho.
4. Comparador multi-rascunho (drafts diferentes lado a lado).
5. Audit trail de eventos de edição em isp_draft_eventos.
6. Integração Friction × Diagnóstico puxando fricao_score dos municípios da etapa 1.

26.13 · O que vem na sequência

O capítulo seguinte da Parte V foi a tela /admin (Cap. 22). Para entender o destino institucional dos drafts promovidos, leia o Anexo G (Manual do Comitê de Investimentos ISP), em particular §G.3 (ciclo de vida da tese) e §G.4 (modo bloqueante vs. advisory). Para o instrumento financeiro associado, releia o Cap. 12 (Princípios ICMA). Para a estrutura causal que sustenta a etapa 2, releia o Cap. 4 (DAGs causais).