wiki/tasks/orchestrator/reports/dev-2026-05-21-orchestrator-qg.md

Dev Report: Orchestrator Quality Gates + Auto-launch

Дата: 2026-05-21 Статус: DONE

Задача

Реализовать Quality Gates и автоматический запуск Claude CLI агентов в Orchestrator при наступлении событий (webhook от Plane/Gitea).

Сделано

• Task 1: Исправить запуск Claude CLI (host vs container)

  • Docker CLI установлен в контейнер
  • docker.sock смонтирован для записи task-файлов
  • Claude binary смонтирован напрямую (/opt/claude-code/bin/claude.exe)
  • .claude и .claude.json смонтированы для auth
  • network_mode: host для доступа к Gitea/Plane через localhost
  • Проверено: claude --print "say hello" работает из контейнера

• Task 2: Реальные QG-проверки (src/qg/checks.py)

  • check_analysis_complete — проверяет 4 файла в docs/work-items/
  • check_architecture_done — проверяет ADR или infra-requirements
  • check_ci_green — Gitea API commit status
  • check_review_approved — Gitea API PR reviews
  • check_tests_passed — наличие test-report.md с PASS

• Task 3: Полная обработка Plane webhooks (src/webhooks/plane.py)

  • work_item.created → генерация ID, создание task в БД, создание ветки в Gitea, создание initial docs
  • comment.created с :approved: → QG check → advance stage → launch agent
  • comment.created с :rejected: → rollback stage

• Task 4: Полная обработка Gitea webhooks (src/webhooks/gitea.py)

  • push с ADR файлами при stage=architecture → advance to development
  • status success при stage=development → advance to review
  • pull_request reviewed/approved → advance to testing
  • pull_request request_changes → back to development (max 3 retries)
  • pull_request closed+merged → stage=done

• Task 5: Stage machine + Notifications

  • src/stages.py — конечный автомат с transitions, agents, QG checks
  • src/notifications.py — structured logging для stage changes, QG failures, errors

• Task 6: Тесты (27 tests, all green)

  • tests/test_qg.py — 16 тестов для всех QG-функций
  • tests/test_webhooks.py — 11 тестов для webhook handlers

• Task 7: Деплой + smoke test

  • Container rebuilt and running
  • Health check passes
  • Webhook creates task + branch in Gitea
  • QG correctly blocks advance when files missing
  • QG passes and launches correct agent when files present
  • Claude CLI produces output (13KB architect response)

Изменённые файлы

• Dockerfile — добавлен Docker CLI
• docker-compose.yml — network_mode: host, docker.sock, claude mounts
• src/config.py — добавлены gitea_owner, default_repo, host_repos_dir, plane_project_id
• src/db.py — добавлены get_task_by_plane_id, get_task_by_repo_branch, update_task_stage, get_next_work_item_id, work_item_id column
• src/main.py — добавлен logging config
• src/stages.py — НОВЫЙ: stage machine
• src/notifications.py — НОВЫЙ: structured logging
• src/qg/checks.py — ПЕРЕПИСАН: реальные проверки
• src/webhooks/plane.py — ПЕРЕПИСАН: полная обработка
• src/webhooks/gitea.py — ПЕРЕПИСАН: полная обработка
• src/agents/launcher.py — ПЕРЕПИСАН: запуск через mounted binary + docker run для task files
• tests/test_qg.py — НОВЫЙ: 16 тестов
• tests/test_webhooks.py — ПЕРЕПИСАН: 11 тестов

Результат

• curl localhost:8500/health → {"status":"ok"}
• pytest tests/ -v → 27 passed
• Webhook work_item.created → task в БД + ветка в Gitea + initial docs
• :approved: при наличии файлов → stage advance + agent launch
• :approved: без файлов → QG failure logged, stage не меняется
• Claude CLI запускается из контейнера, auth работает, output записывается

Проблемы и решения

1. Claude CLI не в контейнере → mount binary + .claude dir напрямую
2. Gitea недоступен из контейнера → network_mode: host
3. OAuth token expired → mount .claude rw для auto-refresh
4. DB schema mismatch → ALTER TABLE для work_item_id column
5. Task file write (repos :ro) → docker run с stdin для записи
6. Agent name bug → get_agent_for_stage(current_stage) вместо next_stage

Ограничения

• Repos mounted :ro — агенты не могут писать напрямую (пишут в stdout/log)
• Claude CLI auth зависит от refresh token — если истечёт, нужен ручной claude на хосте