fix(engine): surface PR read degradation in metrics and the report

[cpenaforte-clickbus]

Contexto e Motivação

A leitura de PRs já sabe quais passos degradaram (#280), mas nada fora dela fica sabendo: o metrics.json e o relatório seguem apresentando dado parcial com a mesma confiança do completo. E a merge strategy faz pior do que omitir: sob enriquecimento degradado, a heurística de fallback só consegue responder squash, então um repositório misto aparece como squash 100%, com as métricas por commit marcadas como não confiáveis — o oposto da verdade. Como o dashboard mostra o run mais recente, um único run degradado basta para o repositório aparecer assim.

Resolver agora porque é esta parte que torna o sinal visível: sem ela, a anterior não muda nada para quem lê o relatório.

Refs #236

Mudanças

• ReportMetrics.pr_enrichment_degraded — os passos que falharam, em ordem e sem repetição. Omitido do JSON quando nada degradou, então um run limpo gera o mesmo metrics.json de antes.
• aggregate(..., pr_fetch_degraded=...) emite o campo, e cli.py e org_runner.py passam o que a leitura reportou — também nos agregados da janela recente e de antes e depois da adoção, porque o metrics.json serializa esses dois últimos em adoption_timeline.
• detect_merge_strategy(..., enrichment_degraded=True) devolve unknown com o motivo, commit_metrics_reliable = true e sem dominant_share, em vez de classificar com uma heurística que só sabe dizer squash.
• O relatório ganha um aviso no topo, ao lado do de repositório não-código, em EN e PT-BR. No topo e não na seção de PRs porque essa seção some quando a leitura perdeu todos os PRs. O aviso não promete que uma nova execução resolve: com o gh instalado mas sem autenticação, toda execução falha, e o texto aponta gh auth status.
• No console, uma leitura que falhou sem trazer PR nenhum aparece como falha, não mais como "pulado (sem remote GitHub ou gh CLI)".
• docs/METRICS.md §15 documenta o campo, e §28 a regra da merge strategy.

Plano de Teste

• pytest tests/test_pr_fetch_degradation.py tests/test_merge_strategy_detector.py tests/test_pr_enrichment_caveat.py -v — o campo no payload e a ausência dele num run limpo; unknown sob degradação contra squash com os mesmos dados; os dois pontos de entrada, cli e org_runner, escrevendo o campo num metrics.json real a partir de um repositório git temporário, inclusive nos agregados de adoção; a linha de console de falha; o aviso em EN e PT-BR, inclusive sem seção de PR — rodado em 10441c4: 36 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 10441c4: local: 371 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 — nenhum módulo de análise novo — rodado em 10441c4: Analysis chain OK

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

Impacto e Risco

• Áreas afetadas: agregador, detector de merge strategy, relatório Markdown, textos EN/PT-BR do engine e docs/METRICS.md.
• Compatibilidade: runs sem degradação geram o mesmo metrics.json e o mesmo relatório. O /api/ingest aceita o campo novo sem alteração (.passthrough(), route.ts:45). Mudança de comportamento deliberada: com o enriquecimento degradado, merge_strategy passa a unknown em vez de um valor enviesado, e o repositório mostra estratégia desconhecida naquele run em vez de squash 100%.
• Performance: nenhuma mudança.
• Segurança: nenhuma superfície nova.
• Acessibilidade e custo AWS: N/A — sem UI e sem infraestrutura.
• Limitação conhecida: com reviews degradado, as métricas de review ainda saem distorcidas aqui — cobertura 0%, single-pass 100% —, e o aviso diz isso. O fix(engine): omit review-derived metrics when the reviews read fails #284, empilhado sobre este, passa a omiti-las.

Sobre o tamanho (RFC 0028 §2.4): 412 linhas, faixa 251–500. Separar o campo do aviso deixaria o relatório calado sobre algo que o JSON já carrega.

PR empilhado: a base é a branch do #280, então o diff mostra só esta parte. Depois do merge do #280, a base passa a ser a main.

Plano de Rollback

git revert do merge deste PR. O campo some do payload e a merge strategy volta a ser classificada 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): report which PR read steps degraded instead of hiding it #280
• Blocks fix(engine): omit review-derived metrics when the reviews read fails #284
• docs/METRICS.md §15 e §28
• RFC 0028, RFC 0029 PM-4

Autoria Assistida

• Agente: Claude Code — Claude Haiku 4.5 e Claude Sonnet 5.5 nos commits; Claude Sonnet 5.5 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 reportar unknown partiu 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:23pm UTC