Docs: skills da GenAI atualizadas e divididas em três

README.md

@@ -141,6 +141,7 @@ O primeiro build leva alguns minutos (PyTorch); os seguintes reaproveitam o cach
 - [`notebooks/dados/01_eda.ipynb`](notebooks/dados/01_eda.ipynb): análise exploratória e as figuras dos slides (`docs/figuras/`).
 - [`docs/bpmn/`](docs/bpmn/): processo em BPMN 2.0.
 - [`genai/FORMATO_JSON.md`](genai/FORMATO_JSON.md) e [`genai/REGRAS_PARECER.md`](genai/REGRAS_PARECER.md): contrato e regras do parecer.
+- [`genai/avaliacao/`](genai/avaliacao/CRITERIOS.md): critérios, os 20 casos de avaliação e os resultados do parecer (prompts v2 a v4), com a revisão humana da v4.
 - [`docs/ROTEIRO_DEMO.md`](docs/ROTEIRO_DEMO.md): roteiro da demo, plano B e perguntas prováveis.
 - [`infra/`](infra/README.md): o mesmo ambiente em Terraform (provider Docker, local, sem custo).
 - [`skills/`](skills/README.md): guia do projeto por setor (estrutura, ambiente, dados, modelo, juro justo, parecer, API, painel, governança).
@@ -168,4 +169,5 @@ Cada frente registra aqui como usou assistentes de IA (agentic coding) e como re
 
 - **Dados:** os scripts de carga, os esquemas SQL e a documentação foram escritos com apoio do Claude e revisados e testados pelo responsável da frente.
 - **App e infraestrutura:** a integração da API com o `prever()`, as telas do painel e os testes foram feitos com apoio do Claude, a partir dos protótipos do grupo e dos contratos (`FORMATO_JSON.md`, `REGRAS_PARECER.md`). A responsável revisou o código e conferiu o resultado com testes automáticos e rodando as telas.
-- **Modelo e GenAI:** a completar por cada frente.
+- **Modelo:** a completar pela frente.
+- **GenAI:** o código do parecer, os prompts e os documentos da frente foram escritos com apoio do Claude, guiado pelos guias da frente em `skills/regras_negocio/` ([`normas_rag`](skills/regras_negocio/normas_rag/SKILL.md), [`parecer_genai`](skills/regras_negocio/parecer_genai/SKILL.md) e [`avaliacao_parecer`](skills/regras_negocio/avaliacao_parecer/SKILL.md)) e pelos contratos (`FORMATO_JSON.md`, `REGRAS_PARECER.md`). As propostas maiores (template, cadeia em LangChain, prompts v3 e v4) também passaram pela revisão de uma segunda IA. A responsável leu cada mudança antes de aplicá-la e conferiu o resultado com os testes automáticos (`tests/genai/`), a avaliação dos 20 casos e a revisão humana dos pareceres (`genai/avaliacao/`).

skills/README.md

@@ -12,7 +12,7 @@ Esta pasta descreve o projeto **por setor**, para que uma IA (ou uma pessoa nova
 
 Marcadores usados: **[PRONTO]** já existe e funciona · **[EM ANDAMENTO]** alguém está fazendo (nome entre parênteses) · **[PENDENTE]** ainda não começou · **[A DECIDIR]** depende de decisão do grupo (o texto diz a escolha padrão).
 
-Atualizado em **06/11/2026**, a partir do repositório nessa data.
+Atualizado em **06/11/2026**, a partir do repositório nessa data. Skills da GenAI (`normas_rag`, `parecer_genai`, `avaliacao_parecer`) atualizadas em **10/11/2026**.
 
 ## Mapa
 
@@ -29,7 +29,9 @@ skills/
     ├── modelo_risco/             variáveis, XGBoost, calibração, métricas, faixas, revisão manual, SHAP
     ├── juro_justo/               fluxo de caixa, convenção nominal, LGD, margem, incerteza, situação do preço
     ├── contratos_dados/          formatos JSON entre as frentes (prever, parecer, API, carteira)
-    ├── parecer_genai/            regras do parecer, RAG, prompt, LLM, checagem e template
+    ├── normas_rag/               normas brasileiras, divisão em trechos, indexação no pgvector e busca
+    ├── parecer_genai/            regras do parecer, prompt, cadeia com o Gemini, conferência e template
+    ├── avaliacao_parecer/        os 20 casos, critérios, métricas e revisão humana do parecer
     ├── auditoria_carteira/       lote da carteira, equidade, backtest, ROI e segmentação
     ├── api/                      FastAPI: rotas, schemas e conversões
     └── painel/                   Streamlit: telas, blocos, design e decisão do analista
@@ -38,7 +40,7 @@ skills/
 ## Ordem de leitura
 
 - **Para entender o projeto:** `visao-geral` → `regras_negocio/governanca` → `regras_negocio/contratos_dados`.
-- **Para construir do zero:** `estrutura-projeto` → `boas-praticas-python` → `ambiente-e-infra` → `dados` → `modelo_risco` → `juro_justo` → `contratos_dados` → `parecer_genai` → `api` → `painel` → `auditoria_carteira`.
+- **Para construir do zero:** `estrutura-projeto` → `boas-praticas-python` → `ambiente-e-infra` → `dados` → `modelo_risco` → `juro_justo` → `contratos_dados` → `normas_rag` → `parecer_genai` → `avaliacao_parecer` → `api` → `painel` → `auditoria_carteira`.
 - **Para mexer em um setor:** leia o `SKILL.md` dele, os setores em "Leia antes" e, sempre, `governanca` e `contratos_dados`.
 
 ## Como usar com uma IA

skills/regras_negocio/avaliacao_parecer/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: auditor-avaliacao-parecer
+description: Use para avaliar o parecer do Auditor de Preço Justo antes de trocar o prompt, o modelo do Gemini ou a busca — os 20 casos, critérios definidos antes dos resultados, avaliar.py, métricas por código, revisão humana e comparação entre versões.
+---
+
+# Avaliação do parecer
+
+> Leia antes: `regras_negocio/parecer_genai`, `regras_negocio/normas_rag`. Dono: Maria (GenAI). Critérios: `genai/avaliacao/CRITERIOS.md` (definidos **antes** dos resultados).
+
+## Objetivo
+
+Medir se o parecer é **certo, fiel às normas e claro** antes de qualquer mudança chegar à demo, e registrar cada versão para comparar.
+
+## Arquivos
+
+`genai/avaliacao/CRITERIOS.md`, `montar_casos.py` (monta os casos e as normas aceitas por situação), `casos_avaliacao.json`, `avaliar.py`, `resultados_<versão>_<modelo>.json` e `.md` (v2, v3 e v4); `tests/genai/test_avaliacao.py`.
+
+## Regras
+
+20 casos: 5 acima, 4 abaixo, 4 dentro, 2 revisão manual, 5 difíceis (motivo com gênero, número extremo, trecho irrelevante, revisão manual prevalecendo, país no rótulo). Critérios: recuperação no top 3 (meta ≥ 80%; a busca v1 atingiu 8/10 e a v4, 16/16), fidelidade, consistência numérica (por código), citação correta, alucinação (meta zero na demo), regras, clareza (1–5). Cada caso rodado 2 vezes.
+
+- Rodar (com o banco indexado e a chave): `python -m genai.avaliacao.avaliar`, que grava `resultados_<versão>_<modelo>.json` e `.md`; `--relatorio` refaz o `.md` a partir do JSON da versão e do modelo atuais.
+- **Atenção:** rodar de novo ou usar `--relatorio` **reescreve o `.md` do zero e apaga a revisão humana**. Antes, faça o commit da revisão; numa versão já revisada, não rode de novo com o mesmo prompt e modelo.
+- As normas aceitas por situação ficam em `montar_casos.py` e só mudam **antes** de rodar uma versão.
+- Métricas por código além dos critérios: fonte específica por situação (sem contar a LGPD art. 20, que entra em todos os casos), citações da LGPD art. 20, recusas por palavra e por artigo.
+- Resultado da v4 (09/11): recomendação 40/40, sem palavra proibida 40/40, mesma resposta nas 2 rodadas 16/20, fonte específica 8/8 no caso "abaixo" e 1/9 no "acima" (as normas tratam de transparência, não de teto de juros). Revisão humana (10/11, 17 pareceres): fidelidade 17/17, alucinação 0/17, citação correta 7/8, clareza média 3,6. As duas quedas para o template (C13 na v3, C03 na v4) foram timeouts do Gemini.
+- Na v4, "fontes dentro das normas aceitas" dá 32/33 por causa do C03: ele citou o CDC art. 54-D, II corretamente (sim na revisão humana), mas esse artigo não estava entre as normas aceitas do caso "acima". A métrica está certa: ela mede o gabarito definido antes de rodar, não se a citação está correta.
+- Os casos e as normas aceitas **não mudam depois de rodar** uma versão: mudar o gabarito depois do resultado invalida a comparação. Os casos com país no rótulo ("Estônia") ficam como estão: testam se o código retira o país.
+- A revisão humana é do **texto original do LLM**, antes dos ajustes de estilo; não reavaliar com os ajustes e dizer que o modelo melhorou.
+- Relatar a fonte específica **por situação**: no caso "dentro" não há problema a apontar, e no "acima" muitas vezes não há norma pertinente (o sistema prefere não citar a citar errado).
+
+## Como construir
+
+1. Banco indexado (`regras_negocio/normas_rag`), `DATABASE_URL` e `GOOGLE_API_KEY` definidos.
+2. Antes de rodar uma versão nova, decidir e registrar se as normas aceitas mudam (`montar_casos.py`).
+3. `python -m genai.avaliacao.avaliar` (cerca de 5 a 10 minutos: há uma pausa de 4 s entre as chamadas, configurável por `PAUSA_ENTRE_CHAMADAS`, para não estourar o limite do plano gratuito do Gemini).
+4. Preencher a revisão humana no `.md` (fidelidade, citação correta, alucinação, clareza 1–5), com legenda, resumo e observações logo abaixo da tabela.
+5. Comparar com a versão anterior e anotar o motivo da próxima versão nas notas do prompt.
+
+## Pronto quando
+
+O `.md` da versão tem as métricas por código e a revisão humana preenchida; recomendação certa e "sem palavra proibida" em 100%; alucinação zero na revisão humana; `tests/genai/test_avaliacao.py` passa.
+
+## Estado em 10/11/2026
+
+- **[PRONTO]** critérios, 20 casos, `avaliar.py` com `--relatorio`, avaliações v2, v3 e v4, revisão humana da v4.

skills/regras_negocio/normas_rag/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: auditor-normas-rag
+description: Use para incluir, trocar ou reindexar as normas do parecer do Auditor de Preço Justo e para mexer na busca (RAG) — fontes oficiais, divisão em trechos, trecho_id, embeddings multilíngues, tabela trechos_normas no pgvector, perguntas de busca por situação e pergunta de governança.
+---
+
+# Normas e busca (RAG)
+
+> Leia antes: `regras_negocio/governanca`. Depois: `regras_negocio/parecer_genai` (quem usa os trechos) e `regras_negocio/avaliacao_parecer` (como medir a busca). Dono: Maria (GenAI). Código: `genai/src/dividir.py`, `indexar.py`, `testar_busca.py`, `cadeia.py` (`buscar_trechos`, `carregar_modelo_embeddings`).
+
+## Objetivo
+
+Guardar as normas brasileiras em trechos pesquisáveis e, para cada contrato, **trazer os trechos que podem sustentar o parecer**. A busca nunca decide nada: só entrega trechos ao LLM, que cita apenas o que recebeu.
+
+## Arquivos
+
+`genai/normas/*.md` + `FONTES.md`; `genai/src/dividir.py` (`dividir_normas`), `indexar.py` (cria a extensão e a tabela, grava os 91 trechos), `testar_busca.py` (10 perguntas de resposta conhecida); `buscar_trechos` em `genai/src/cadeia.py`; `genai/avaliacao/resultado_busca_v1*.txt`.
+
+## Regras
+
+- Normas em `genai/normas/`, copiadas de fonte oficial e limpas (sem anotações, revogados ou vetados), com `FONTES.md` (arquivo, norma, artigos, URL, data de acesso):
+  - `lgpd.md` Lei 13.709/2018, arts. 5º, 6º, 7º, 11, 12, 20
+  - `cdc.md` Lei 8.078/1990, arts. 2º, 3º, 4º, 6º, 30, 31, 39, 42, 42-A, 46, 47, 52, 54, 54-A a 54-D, 54-F, 54-G, 104-A a 104-C
+  - `cet.md` Res. CMN 4.881/2020, arts. 1º a 9º
+  - `credito_oferta.md` Res. CMN 5.004/2022, arts. 1º a 9º
+  - `ref.md` Relatório de Estabilidade Financeira do BC (maio/2026), seção 2.1 e apêndice, dividido por parágrafo
+- **Divisão:** um trecho por artigo; longos quebrados entre incisos/parágrafos (`TAMANHO_MAXIMO = 1000`, sobra < `TAMANHO_MINIMO = 300` junta à anterior, repete `TAMANHO_CAPUT = 150` caracteres do caput).
+- **`trecho_id`:** `<arquivo>-art<número>-<parte>` (`cdc-art6-1`, `cdc-art54b-1`, `lgpd-art20-1`); REF `ref-p<parágrafo>-1`. O inciso vai no campo `artigo` da fonte ("art. 6º, III").
+- **Indexação:** `sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2` (384 dimensões) na tabela `trechos_normas` do pgvector.
+- **Busca (`buscar_trechos`):** uma pergunta fixa por situação (`PERGUNTAS_BUSCA`) traz os **4** trechos mais próximos (`QUANTOS_TRECHOS`), mais **1** trecho da pergunta de governança (`PERGUNTA_GOVERNANCA`, revisão de decisões automatizadas, que traz a LGPD art. 20), sem repetir trecho. Cada trecho tem `norma`, `artigo`, `trecho_id`, `texto`. Sem banco → segue sem trechos (o parecer sai sem fontes, nunca falha).
+- O LLM cita só o que recebeu. Sem trecho pertinente → `fontes: []`; a tela mostra "Não encontrei base normativa para este caso."
+- **Não direcionar** a busca do caso "acima" para o CDC art. 39 (ele está indexado, mas a pergunta evita): o texto começa com "práticas abusivas", e o LLM tenderia a copiar a palavra proibida. Três trechos indexados têm palavras proibidas no texto da lei (`cdc-art6-1`, `lgpd-art6-2`, `lgpd-art20-1` § 2º): o prompt pede para não copiá-las.
+- Uma norma nova só entra com fonte oficial registrada no `FONTES.md`; depois, reindexar e rodar o `testar_busca.py` de novo. O `indexar.py` apaga a tabela e grava todos os trechos de novo (não há indexação parcial), o que leva poucos segundos depois que o modelo foi baixado.
+
+## Como construir
+
+1. Copiar a norma da fonte oficial para `genai/normas/<arquivo>.md`, limpa, e registrar no `FONTES.md`.
+2. `python genai/src/dividir.py` para conferir os trechos (contagem por norma e tamanhos).
+3. Com o banco no ar e `DATABASE_URL` definida: `python genai/src/indexar.py` (na 1ª vez baixa o modelo de embeddings, ~470 MB). No ambiente da demo, o `iniciar.ps1` faz este passo.
+4. `python genai/src/testar_busca.py`: meta de **8 de 10** perguntas com o artigo certo entre os 3 primeiros.
+5. Mudou uma pergunta de busca? Rodar a avaliação do parecer (`regras_negocio/avaliacao_parecer`) e comparar a recuperação.
+
+## Pronto quando
+
+`indexar.py` grava **91 trechos** (CDC 37, LGPD 17, REF 17, Res. 4.881 9, Res. 5.004 11); `testar_busca.py` acerta pelo menos 8 de 10 (a v1 acertou 8/10); na avaliação, a recuperação fica em pelo menos 80% (na v4: 16/16). Os testes de `buscar_trechos` em `tests/genai/` passam (busca sem banco devolve lista vazia; a pergunta de governança não repete trecho).
+
+## Estado em 10/11/2026
+
+- **[PRONTO]** normas, `FONTES.md`, divisão, indexação, busca v1 (8/10), pergunta de governança (v3), indexação automática no `iniciar.ps1`.