# Dev Report: Orchestrator Quality Gates + Auto-launch
Дата: 2026-05-21
Статус: DONE

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

## Сделано

- [x] 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"` работает из контейнера

- [x] 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

- [x] 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

- [x] 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

- [x] Task 5: Stage machine + Notifications
  - `src/stages.py` — конечный автомат с transitions, agents, QG checks
  - `src/notifications.py` — structured logging для stage changes, QG failures, errors

- [x] Task 6: Тесты (27 tests, all green)
  - `tests/test_qg.py` — 16 тестов для всех QG-функций
  - `tests/test_webhooks.py` — 11 тестов для webhook handlers

- [x] 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` на хосте