Skip to content

ADR-0001: Five Concurrent Async Loops

Status: Accepted (amended 2026-04-25) Enforced by: tests/test_orchestrator_loops.py, tests/architecture/test_loop_count_matches_adr0001.py Date: 2026-02-26

Context

HydraFlow must process GitHub issues through five distinct stages: triage, plan, implement, review, and human-in-the-loop (HITL) correction. Each stage has different latency profiles:

  • Triage: fast (seconds) — scoring + label assignment
  • Plan: slow (minutes) — codebase exploration + plan generation
  • Implement: very slow (many minutes) — full code changes + quality gate
  • Review: slow (minutes) — diff analysis + optional fixes
  • HITL: human-gated (indefinite) — waits for operator action

Multiple issues exist in the pipeline simultaneously, and stages are independent of each other (issue #10 can be in triage while issue #5 is in review).

Background

This ADR was originally written when HydraFlow had five concurrent async loops. The decision below is preserved as historical context; the live system now runs ~30 loops including the caretaker fleet (ADR-0029) and the trust fleet (ADR-0045). The current count is reflected in the live registry at docs/arch/generated/loops.md, regenerated by the DiagramLoop (L24) on a 4-hour cadence and CI-guarded against drift on every PR.

The five-loop framing remains accurate for orchestration-stage loops (triage/plan/implement/review/HITL); subsequent ADRs added orthogonal loop fleets (caretaking, trust, dashboard, etc.) without invalidating the original decomposition for the orchestration pipeline.

Decision

Run five concurrent asyncio polling loops from orchestrator.py, one per stage. Each loop independently: 1. Fetches its work queue (issues with the relevant label) from GitHub. 2. Processes items up to a configurable batch size and concurrency limit. 3. Sleeps for a configurable interval between polls. 4. Respects a shared stop_event for graceful shutdown.