fix(engine): omit review-derived metrics when the reviews read fails

[cpenaforte-clickbus]

Contexto e Motivação

Quando a passada de reviews da leitura de PRs falha, todo PR chega sem review. As métricas derivadas de review não ficam só incompletas — ficam fabricadas: a cobertura de review humana só pode dar 0%, o single-pass só pode dar 100%, as fases de flow viram uma única espera "aguardando primeira review", e PR aberto parece mais parado do que está. A narrativa do relatório afirma isso como fato: "nenhum PR teve revisão humana", "wait time dominates".

Resolver agora pela mesma razão da merge strategy em #281: campo ausente é melhor que número fabricado (decisão D3 do autor, análoga à D1). E essa passada é justamente a que o próprio código documenta como sujeita a 504.

Refs #236

Mudanças

• Com reviews degradado, o aggregate() não emite: pr_review_rounds_median, pr_single_pass_rate, median_time_to_first_review_hours, human_review_coverage_pct, human_approval_coverage_pct, human_review_coverage_by_intent, human_review_coverage_by_origin_of_pr; o bloco de flow inteiro (flow_efficiency_median, time_in_phase_median_hours, flow_pr_count, flow_efficiency_by_*); as métricas de PR aberto parado (stale_open_pr_pct, very_stale_open_pr_pct, abandonment_risk_pct, stale_open_pr_pct_by_origin); e as chaves single_pass_rate / median_review_rounds dos grupos de acceptance_by_*.
• Continua emitindo o que não depende de review: contagem e tempo até merge de PR, tamanhos, buckets de cycle time, contagem e idade de PR aberto, e o pr_rate dos grupos de acceptance.
• O relatório, a narrativa e a comparação de tendência passam a tolerar esses campos ausentes: a linha some, a célula mostra —, o delta não é calculado.
• docs/METRICS.md §15, §25 e a seção de PR aberto dizem quando cada campo é omitido.

Plano de Teste

• pytest tests/test_pr_fetch_degradation.py -v — com reviews degradado, todos os campos acima ausentes e os de PR aberto por idade presentes; num run limpo com os mesmos PRs, todos presentes; relatório renderizando sem as métricas de review; tendência sem o delta de single-pass quando um lado não tem o valor; narrativa sem quebrar — rodado em 52ded1f: 26 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 52ded1f: local: 376 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
• python scripts/check_analysis_chain.py — rodado em 52ded1f: Analysis chain OK

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, relatório, narrativa, comparação de tendência e docs/METRICS.md.
• Compatibilidade: runs sem reviews degradado geram o mesmo metrics.json e o mesmo relatório. Runs com reviews degradado passam a não trazer os campos listados. Ordem de deploy: a plataforma multiplica single_pass_rate dos grupos de acceptance; sem a tolerância do feat(platform): mark incomplete PR data on compare and dashboard #283, um payload deste engine viraria NaN% no dashboard. O feat(platform): mark incomplete PR data on compare and dashboard #283 entra e é publicado antes deste, e nenhuma release do CLI com esta mudança sai antes disso.
• 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): 362 linhas, faixa 251–500. A omissão e a tolerância dos leitores formam uma mudança só: omitir sem ajustar relatório, narrativa e tendência quebraria o run degradado.

Plano de Rollback

git revert do merge. Os campos voltam a ser emitidos — distorcidos sob reviews degradado, como antes; 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): surface PR read degradation in metrics and the report #281 — PR empilhado: a base é a branch dele
• Depends on feat(platform): mark incomplete PR data on compare and dashboard #283 — a tolerância da plataforma precisa estar em produção antes
• Blocks feat(engine): flag repos with a degraded PR read in org outputs #285
• docs/METRICS.md §15 e §25
• RFC 0028, RFC 0029 PM-4

Autoria Assistida

• Agente: Claude Code — Claude Sonnet 5.5 nos commits e nas revisões por task; Claude Opus 5.5 na orquestração e na revisão final do conjunto
• Escopo da assistência: a decisão de omitir (D3) foi do autor; desenho e implementação guiada por testes foram assistidos
• 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 5, 2026 6:59pm UTC