docs/METODOLOGIA_IDS_v5.md

# IDS v5 — avanço legislativo verificável

Revisão de 29 de outubro de 2026. Responsável: Observatório do Senado.

## Diagnóstico

A efetividade anterior consultava nomes de campos que não correspondiam ao
contrato atual da API. A listagem `/processo` entrega `situacaoAtual` e
`normaGerada`, mas a classificação procurava principalmente
`descricaoSituacao`, `situacao` e palavras na deliberação. Uma proposição
transformada em lei podia ficar apenas como aprovada no Senado. Outros erros:

- `tramitando=Sim` recebia crédito de tramitação avançada sem evidência de avanço;
- qualquer texto contendo “aprovad” ou “remetid” podia parecer aprovação;
- requerimentos aprovados contribuíam para efetividade normativa;
- a consulta por “tramitou na legislatura atual” incluía projetos apresentados
  antes da janela, favorecendo carteiras acumuladas em mandatos anteriores;
- a apuração anual atribuía o status de hoje a projetos de anos passados;
- a normalização descartava uma dimensão inteira se a maioria tinha o mesmo
  valor, embora muitos zeros sejam possíveis em resultados legislativos;
- comparações temporais não distinguiam explicitamente versões do método.

## Fundamento científico e decisão

A literatura de efetividade legislativa considera tanto a apresentação quanto
o avanço e a transformação em lei. O Center for Effective Lawmaking utiliza
estágios, importância substantiva e participações relativas na produção do
conjunto. Isso sustenta observar etapas verificáveis, mas **não valida os
coeficientes específicos do IDS**. O sistema brasileiro também tem ritos
diferentes: uma resolução do Senado não precisa percorrer as duas Casas e
uma PEC não depende de sanção presidencial.

Adotamos uma escala ordinal de avanço com incrementos iguais e uma proporção
ponderada de avanço da carteira. O volume permanece na dimensão de
produtividade. Esta é uma opção operacional interpretável, não uma réplica do
LES americano nem um estimador de mérito, esforço ou impacto causal. Uma escala
ordinal não determina por si só distâncias cardinais: transformar as etapas em
0, 1, 2, 3 e 4 é uma convenção explícita, examinada por sensibilidade.

Uma alternativa é normalizar a contribuição de cada parlamentar pelo total
alcançado em cada etapa, como no LES. Ela atribui peso implícito maior aos eventos
raros e mede contribuição agregada; não é equivalente à taxa de avanço da
carteira. Outra alternativa é modelar tempo até cada transição, com censura à
direita e ajuste por tipo, ano, posição institucional e coautoria. Isso exige
reconstruir e validar uma base longitudinal antes de estimar parâmetros. Não se
deve apresentar multiplicadores escolhidos intuitivamente como resultados desse
modelo, nem presumir que o ajuste por meses de mandato resolve a idade dos projetos.

Referências primárias:

- [Center for Effective Lawmaking — Methodology](https://thelawmakers.org/methodology).
- [OCDE/JRC — Handbook on Constructing Composite Indicators (2008)](https://www.oecd.org/en/publications/handbook-on-constructing-composite-indicators-methodology-and-user-guide_9789264043466-en.html).
- [JRC — análise de sensibilidade](https://knowledge-for-policy.ec.europa.eu/composite-indicators/toolkit_en/navigation-page/10-step-guide_en/step-8-sensitivity-analysis_en).
- [Senado — documentação da API](https://legis.senado.leg.br/dadosabertos/api-docs/swagger-ui/index.html).
- [Senado — projetos de lei, decreto e resolução](https://www12.senado.leg.br/perguntas-frequentes/perguntas-frequentes/canais-de-atendimento/atividade-legislativa/o-que-sao-projetos-de-lei-de-decreto-legislativo-e-de-resolucao).

## Unidade, evidência e janela

A unidade é a proposição, deduplicada por identificador e, quando disponível,
pelo processo original. Ela entra na carteira de cada autor registrado. A
efetividade cobre PEC, PLP, PL, PLS, PLC, PLN, PDL, PDS, PRS e PRN. Requerimentos
e indicações permanecem na produtividade. MPV não integra a efetividade de
autoria, pois sua iniciativa é do Executivo. Tipos desconhecidos não recebem
crédito normativo por aproximação textual.

Entram autorias apresentadas desde 01/02/2023 até o corte, limitado a 31/01/2027.
A consulta usa datas explícitas, sem depender da legislatura corrente da API.
Na edição anual entram autorias apresentadas naquele ano e seus avanços até o
fim do mesmo ano; anos em curso terminam na data da coleta. Assim, esta dimensão
mede o avanço da carteira apresentada no recorte, não toda a atividade sobre
projetos antigos ocorrida nele.

O coletor consulta a listagem e os detalhes de cada proposição normativa. Usa
`autuacoes` da autuação principal, situações com datas, deliberação, destino e
norma gerada. Parecer genérico pode ser pela rejeição: só recebe ponto de
instrução quando o informe associado confirma posição favorável. O campo
`objetivo`, a ementa, a tramitação genérica e a aprovação de requerimento
incidental não demonstram aprovação do projeto.

| Maior estágio comprovado até o corte | Pontos |
| --- | ---: |
| Apresentação / nenhum avanço comprovado | 0 |
| Parecer favorável aprovado ou aptidão/inclusão para deliberação plenária | 1 |
| Aprovação no Senado, inclusive terminativa, ou destinação à Câmara | 2 |
| Destinação à sanção ou promulgação | 3 |
| Transformação em norma jurídica | 4 |

A remessa à Câmara não é aprovação pela Câmara. É o mesmo patamar da aprovação
no Senado, com rótulo próprio para auditoria. Destinação à promulgação não prova
promulgação. Uma norma produz **4 pontos**, nunca 1 + 2 + 3 + 4. Os estágios são
exclusivos nas contagens exibidas. O tipo jurídico conserva seu peso na soma;
os pontos da etapa são mostrados separadamente.

Uma norma com veto parcial conta como norma. Veto total não conta como norma.
Rejeição, retirada ou arquivamento não geram pontos novos, mas não apagam marcos
anteriores comprovados. Isso mede avanço alcançado, e não apenas situação final.
Registros posteriores ao corte ou sem data verificável não acrescentam pontos;
os sem data são sinalizados. Ausência de prova não é prova de inatividade.

## Fórmula e regularização

Para cada parlamentar, sejam `w_j` o peso do tipo e `p_j` a maior etapa do
projeto normativo `j`:

```text
E = Σ(w_j × p_j) / (4 × Σw_j)
n_efetivo = (Σw_j)² / Σ(w_j²)
E_ajustado = (n_efetivo × E + K × média_referência) / (n_efetivo + K)
K = 12
```

`E` varia entre 0 e 1. Não é a proporção de leis aprovadas: uma carteira inteira
enviada à Câmara tem `E = 0,5`; uma carteira inteira transformada em norma tem
`E = 1`. Sem proposições normativas, o score é zero. A média de referência usa
somente elegíveis com propostas normativas (12 meses na legislatura, 6 no ano).

`n_efetivo` desconta a concentração dos pesos: multiplicar uniformemente os
pesos não altera o ajuste e uma PEC não equivale a três observações independentes.
É uma medida de concentração usada para regularização, não uma garantia de
independência estatística. Propostas e coautorias podem ser correlacionadas.
`K = 12` significa doze propostas efetivas; **não significa doze meses**.
Não há afirmação de estimação empírica ótima nem distribuição posterior validada.

A nota de efetividade é o percentil empírico de `E_ajustado` entre os elegíveis
com propostas normativas: `100 × (n_abaixo + n_empatados/2) / N`. Os empates usam
tolerância numérica de 1e-12. Se toda a referência é zero, a nota é zero. Muitos
zeros não apagam quem tem resultados. As outras cinco dimensões mantêm a
transformação z-score/CDF e seus pesos. A nota final é uma média ponderada de
dimensões, não um percentil observado nem necessariamente uma distribuição normal.

Pesos globais preservados: produtividade 20%, efetividade 24%, participação 20%,
fiscalização 13%, CEAP 11% e transparência 12%. Pesos por tipo são convenções
formais, não avaliações da importância substantiva de cada projeto.

## Auditoria e sensibilidade reproduzíveis

```bash
pnpm --filter worker test:tramitacao
pnpm --filter worker exec tsx scripts/auditar-tramitacao.ts
```

O segundo comando consulta apenas fontes públicas. Não abre banco, credenciais
ou cache de produção e não publica resultados. `--limite=8` permite uma amostra
determinística por código. `--cache-publico=/tmp/auditoria` mantém apenas as
respostas públicas em pasta escolhida para retomar consultas. Sem essa opção o
cache temporário é apagado ao terminar. A saída JSON contém decomposição por
parlamentar e sensibilidade a:

- incrementos lineares 0/1/2/3/4;
- mais peso no resultado final: 0/0,5/1/2/4;
- mais peso intermediário: 0/1,5/2,5/3,5/4;
- K = 6 e K = 24;
- pesos iguais entre tipos normativos.

Compara correlação de Spearman com empates e deslocamentos de posição. Trata-se
da **ordenação da efetividade**, não do IDS total; correlação alta não substitui
inspeção de mudanças locais e não valida o mérito das leis. Os parâmetros não
são escolhidos para maximizar posições de parlamentares específicos.

## Resultado da auditoria de 29/10/2026

A coleta cobriu os 107 parlamentares da coorte (82 elegíveis), com 13.915
proposições distintas. Foram 29.553 registros de autoria, dos quais 7.535 de
proposições normativas. Uma proposição com vários autores aparece na carteira
de cada um; portanto, 7.535 não é a quantidade de projetos normativos distintos.
Entre essas autorias normativas: 5.942 sem marco comprovado, 808 no patamar
intermediário, 381 destinadas à Câmara, 4 à sanção/promulgação e 400 transformadas
em norma. Não houve evidência de avanço descartada por ausência de data nesta
coleta. Isso verifica o processamento da fonte, não a completude histórica dela.

Sensibilidade **entre os 82 elegíveis**, na ordenação da efetividade:

| Alternativa ao cenário linear K=12 | Spearman | Maior deslocamento | Média absoluta | Top 10 preservado |
| --- | ---: | ---: | ---: | ---: |
| Maior peso na norma final | 0,9591 | 25 | 4,78 | 7/10 |
| Maior peso nos estágios intermediários | 0,9899 | 12 | 2,44 | 10/10 |
| K = 6 | 0,9989 | 5 | 0,56 | 10/10 |
| K = 24 | 0,9979 | 9 | 0,85 | 9/10 |
| Mesmo peso para todos os tipos | 0,9496 | 23 | 6,00 | 8/10 |

A correlação agregada é alta, mas existem mudanças locais relevantes. Não se
pode chamar a ordenação de insensível aos pesos, nem interpretar uma diferença
pequena de posição como diferença comprovada de qualidade. A variação de K é
menor entre os elegíveis do que na coorte inteira, consistente com a proteção
por amostra mínima. A escala linear foi mantida por sua interpretação simples,
não por produzir vencedores desejados.

O [relatório JSON](IDS_v5_AUDITORIA_2026-10-29.json) contém os agregados públicos,
resultados de cada cenário na coorte inteira e entre os elegíveis, e resumos
por código parlamentar. Não inclui dados do banco de produção, nomes privados,
credenciais ou contatos. Esta auditoria não recalculou nem publicou o IDS total.

## Limites e melhorias necessárias

- Projetos mais recentes tiveram menos tempo para avançar. Cortes temporais
  evitam informação futura, mas não eliminam censura à direita.
- Coautoria recebe crédito integral. O ranking não identifica a contribuição
  causal individual e pode favorecer carteiras coletivas.
- Aprovação depende também de maioria, liderança, agenda, Câmara e Executivo.
  A v5 não estima o efeito causal desses fatores.
- A razão de avanço pode diminuir quando novos projetos ainda sem avanço
  entram na carteira. A produtividade registra esse aumento separadamente.
- Não se reconhece automaticamente texto incorporado a outra proposição;
  históricos incompletos podem subestimar o avanço.
- Ritos, tipos e importância substantiva diferem. Lei, emenda constitucional,
  decreto e resolução são normas, mas não têm necessariamente o mesmo impacto.

Uma próxima validação deve codificar manualmente uma amostra estratificada de
proposições, medir concordância entre avaliadores e comparar com dados da Câmara.
Só depois convém estimar modelos de transição e calibração fora da amostra.

## Integração e ativação

`raw:v5` e `processos:v5` impedem reutilizar agregados do cálculo anterior. O TTL
é de seis horas. As chamadas têm concorrência limitada, ritmo de quatro inícios
por segundo, tentativas adicionais e respeito a `Retry-After` em HTTP 429. Falha
de coleta obrigatória interrompe o novo ranking; não substitui autorias por zero.

A migração em `POST /admin/migrate` acrescenta `metodologia_versao`,
`tramitacao_json` e `efetividade_ajustada`. Históricos antigos continuam v4 e
não recebem contagens de avanço fabricadas. API, perfis, premiação, certificados
novos e comparações da newsletter transportam a versão. A escrita do snapshot
é transacional. Edições aprovadas e PDFs existentes não são recalculados.

Ativar exige a sequência operacional autorizada: disponibilizar a API v5,
executar a migração antes do recálculo, gerar e conferir o primeiro snapshot
completo, então publicar o frontend correspondente. Evitar o cron entre a troca
do código e a migração. A primeira coleta é mais longa por consultar históricos;
confirmar o limite de duração do serviço antes da ativação. Até haver dois
snapshots compatíveis, a newsletter não apresenta deltas entre v4 e v5.