fix(engine): omit what a failed PR list feeds, per state

[cpenaforte-clickbus]

Contexto e Motivação

Com a degradação por estado (#290), sobrou um caso que ainda inventava números: quando a listagem de um estado falha — gh pr list --state merged, a maior e a mais sujeita a timeout —, os outros estados chegam e o agregador calcula como se os PRs mergeados não existissem. A acceptance saía com 0% em todo grupo, o timeline com 0 merges por semana, o WIP subcontado. A detecção de erro transitório também casava timeout e EOF dentro de nomes de repositório e de palavras como "thereof".

Refs #236

Mudanças

• Um estado cuja listagem falhou conta como ausente para tudo o que ele alimenta: merged → merge strategy, ciclo de vida do PR, review, cobertura humana, flow, acceptance e os merges por semana do timeline; open → todas as métricas de PR aberto, inclusive contagem e idades; flow_load, que usa todos os estados, sai quando qualquer listagem falhou (com o author_concurrency junto, para não mudar o formato que a plataforma lê).
• A detecção de erro transitório tira o owner/name do stderr antes de casar e usa limites de palavra.
• O aviso do relatório (EN e PT-BR) passa a citar as métricas de ciclo de vida do PR e as de PRs abertos entre as que podem faltar ou sair distorcidas.
• docs/METRICS.md alinhado: cada célula de "nullable when" diz o estado que a alimenta, o enriquecimento parcial conta como falha, o flow sob enriquecimento parcial sai distorcido e não ausente, e a omissão do flow_load está registrada.

Plano de Teste

• pytest tests/test_pr_fetch_degradation.py -v — listagem merged falhando com open e closed reais: nenhum campo alimentado pelos merged sai com zero; listagem open falhando: nenhuma métrica de PR aberto; listagem closed falhando: o payload igual ao limpo menos o flow_load; o fallback sem a informação por estado aplicando a união; repositório chamado timeout-svc e a palavra "thereof" sem nova tentativa, HTTP 504 e EOF com — rodado em d0ae092: 90 passed
• pytest tests/ -q — a suíte inteira, com o portão de determinismo da [FEAT] Comparador de paridade do metrics.json, campo a campo #214 — rodado em d0ae092: local: 446 passed; a única falha é a test_status_reflects_state ([BUG] test_agent_settings_hook lê o spool real — falha em máquina com registros pendentes #146), que só ocorre fora do CI, e o test_hook_binders.py ficou de fora por depender de rede; no CI o comando literal passa

A verificação roda fora da máquina de quem construiu: o job cli do CI (RFC 0029, PM-4).

Impacto e Risco

• Áreas afetadas: agregador, detecção de erro transitório no leitor, texto do aviso e docs/METRICS.md.
• Compatibilidade: um run sem degradação sai byte a byte idêntico. Runs com uma listagem falhando passam a omitir o que ela alimenta; com a listagem merged falhando, a merge strategy fica ausente em vez de unknown.
• Performance: nenhuma mudança.
• Segurança: nenhuma superfície nova.
• Acessibilidade e custo AWS: N/A — sem UI e sem infraestrutura.

Sobre o tamanho (RFC 0028 §2.4): 470 linhas, faixa 251–500. É o último corte das correções de engine; separar a regra da documentação que a descreve deixaria a doc errada na main.

Plano de Rollback

git revert do merge. Volta a regra só de enriquecimento e reviews por estado; nada a migrar.

Referências

• Issue: [DEBT] PR enrichment degrades silently when the GraphQL step fails; the report carries no signal #236
• Depends on fix(engine): gate degradation per PR state and retry transient errors #290 — PR empilhado: a base é a branch dele
• docs/METRICS.md §9, §10, §15, §24, §28
• RFC 0028, RFC 0029 PM-4

Autoria Assistida

• Agente: Claude Code — Claude Opus 5.5 nos commits, na orquestração e nas revisões finais
• Escopo da assistência: achados da revisão final e implementação guiada por testes; a decisão de omitir em vez de estimar foi do autor
• Revisão humana: pendente — o autor revisa antes do merge

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
clickbus-iris	Ready	Preview	Oct 8, 2026 12:35pm UTC