feat(supervisor): dependency-aware task progression engine

[xsovad06]

Problem

Task progression through the pipeline (triage -> research -> spec -> develop -> review -> address -> integrate) is manually driven. The user must check which tasks are ready, verify dependencies are met, check agent slot availability, and spawn the right role. With multiple tasks across projects, this orchestration overhead dominates the user's time.

The most painful failure mode: spawning a researcher on an issue whose dependencies aren't merged to main yet. The researcher discovers mid-work that prerequisite code doesn't exist and wastes a full cycle.

Solution

A deterministic state machine that auto-advances tasks when conditions are met, gated on the dependency graph. No LLM calls -- every decision is computed from observable state.

Components

• New service sova/supervisor/progression.py:

  • TaskProgressionEngine class:

    • evaluate_all() -> list[ProgressionDecision] -- scan all active tasks, determine next action for each
    • evaluate_task(issue_number) -> ProgressionDecision(action, reason, blocked_by?) -- evaluate a single task
    • execute_decision(decision) -- spawn agent or send notification based on decision

  • State machine transitions:

    BACKLOG       --[manual]-->       TRIAGED
    TRIAGED       --[auto/manual]-->  RESEARCHED     (spawn researcher)
    RESEARCHED    --[checkpoint]-->   SPEC_APPROVED  (human approves spec)
    SPEC_APPROVED --[auto]-->         IN_PROGRESS    (spawn developer)
    IN_PROGRESS   --[auto]-->         IN_REVIEW      (auto-handoff handles)
    IN_REVIEW     --[auto]-->         ADDRESS_REVIEW (when findings detected)
    IN_REVIEW     --[auto]-->         READY_FOR_HUMAN (all gates pass)
    READY_FOR_HUMAN --[checkpoint]--> INTEGRATING    (human approves)
    INTEGRATING   --[auto]-->         DONE           (integrate-pr runs)
    

  • Pre-spawn gate checks (ALL must pass before spawning any agent):

    1. Dependency graph: all deps merged to main (dependency_graph.is_ready(issue))
    2. CodeRabbit quota: enough headroom for eventual PR (coderabbit_service.can_create_pr())
    3. Agent slots: available capacity (respect max_concurrent config)
    4. Budget: within per-task and per-issue limits

  • Human checkpoints (configurable per transition):

    • Spec approval (default: manual -- user reviews spec before development starts)
    • Integration approval (default: manual -- user reviews PR before merge)
    • Ambiguous review resolution (always manual)

• Config:

  [supervisor]
  enabled = false
  auto_research = true          # auto-spawn researcher after triage (when deps met)
  auto_develop = false          # require spec approval first (human checkpoint)
  auto_address_review = true    # auto-address review findings
  auto_integrate = false        # require human integration approval
  respect_dependencies = true   # gate spawning on dependency graph
  poll_interval_seconds = 120

  Triple-registered per architecture rules.

Determinism principle

No LLM calls in the progression engine. Every decision is computed from observable state (issue labels, PR status, CI checks, dependency graph, rate limits). LLM agents are only spawned for creative work (development, review, address-pr). This follows the project's determinism philosophy: agents only for creative work, everything else is deterministic code.

Dependencies

• feat(supervisor): configurable PR integration readiness gates #292 (PR integration readiness gates -- gate checks for progression decisions)
• feat(supervisor): task dependency graph engine #293 (task dependency graph engine -- dependency-aware spawning)
• feat(supervisor): background PR lifecycle monitor with auto-retry #295 (PR lifecycle monitor -- PR state feeds into progression decisions)

Acceptance Criteria

• State machine correctly transitions tasks through all defined states
• Dependency gating: researcher NOT spawned until all deps are merged to main
• CodeRabbit quota check before spawning work that will produce a PR
• Budget check before every agent spawn
• Human checkpoints are configurable (auto vs manual per transition)
• evaluate_task() returns clear reason when a task is blocked
• Config section triple-registered with all fields
• No LLM calls in progression logic (deterministic only)
• Tests cover all transitions, blocking conditions, checkpoint behavior, and multi-task evaluation

Part of

Chain L: Supervisor Agent (Phase 7)