docs(ops): FDD-OPS-019 — investigate Jira JQL pagination cap (BG short-fetch)

[nascimentolimaandre-cloud]

Summary

Documenta achado durante backfill comprehensive de 2026-04-30: projeto BG terminou com status='done' mas processou apenas ~64% das issues (126k de 197.760), sem error/crash/timeout. Hipótese principal: hard cap interno da Jira em cursor pagination com ORDER BY updated em buscas muito antigas (since=2020).

Por que abrir agora (ao invés de fix imediato)

Coverage atual após backfill é 54% tenant-wide (era 13% pré-fix). Métricas funcionam corretamente para os 240k issues frescos. Os ~72k BG issues "missing" mantém dados antigos mas:

• Incremental sync corrige naturalmente quando elas são editadas no Jira
• Aceitável para PoC + Webmotors demos
• Não bloqueia R1

Crítico antes de enterprise tenants com projetos > 100k.

Investigation plan (proposto, S = 1 dia)

1. Confirmar cap via instrumentação — log granular em fetch_issues_batched, capturar resposta crua quando nextPageToken vai vazio
2. Workaround comprovado: date-chunking — quando pre-flight count > 100k, partir JQL em janelas de tempo (updated >= 2020 AND < 2022, etc.). Compatível com per-scope watermarks (FDD-OPS-014) e per-scope progress (FDD-OPS-015) já shippadas.
3. Atomic JQL counting — validar somatório bate com approximate-count
4. Fallback em produção — telemetria detecta items_done < items_estimate × 0.9 e cria event no pipeline_events

Acceptance criteria

Given a Jira project with > 100k issues
 When sync_worker runs full backfill (since=2020)
 Then either:
   (a) all >99% issues are fetched, OR
   (b) clear WARN log + pipeline_event identifies the under-fetch
       AND next cycle automatically retries the missing window

Given the date-chunking workaround is implemented
 When backfill runs on BG (197k issues)
 Then items_done >= 197000 (within 1% of estimate)
  AND total cycle duration < 90 min
  AND no batches lost or duplicated

Stats

• 1 arquivo, +116 linhas (apenas backlog doc)
• Code change deferido para sessão dedicada de implementação

🤖 Generated with Claude Code