auto-sync: 2026-06-01 11:20:01

2026-06-01 11:20:01 +03:00
parent 604909bca6
commit 3de37e615e
2 changed files with 203 additions and 51 deletions
--- a/tasks/multi-agent/ORCHESTRATOR_DOCS.md
+++ b/tasks/multi-agent/ORCHESTRATOR_DOCS.md
@@ -65,6 +65,7 @@ created → analysis → architecture → development → review → testing →

 | QG | Функция | Что проверяет |
 |----|---------|---------------|
+| QG-0 | Валидация при создании Issue | title 5-80 chars, description ≥2 предложений |
 | check_analysis_approved | `:approved:` в комментарии Plane от стейкхолдера | Человеческое подтверждение ТЗ |
 | check_architecture_done | Наличие ADR файлов в `docs/work-items/<id>/06-adr/` | Архитектура задокументирована |
 | check_ci_green | Gitea commit status API | CI pipeline зелёный |
@@ -73,6 +74,67 @@ created → analysis → architecture → development → review → testing →

 ---

+## Plane Integration (полная)
+
+### Статусы Issue
+
+| Статус | ID | Когда | Что значит для Славы |
+|--------|-----|-------|---------------------|
+| **Backlog** | `113b24f6...` | Создан, ещё не взят | Ничего не происходит |
+| **Todo** | `2c7d3df3...` | Прошёл QG-0, ждёт запуска | Скоро начнётся |
+| **In Progress** | `b873d9eb...` | Агент работает | Система работает, ждать |
+| **Needs Input** | `babf08a3...` | Analyst задал вопросы | **Слава, ответь в комментарии** |
+| **In Review** | `38fb1f64...` | ТЗ готово, ждёт approve | **Слава, прочитай и `:approved:` / `:rejected:`** |
+| **Blocked** | `6c4543f9...` | Ошибка / retry исчерпаны | **Нужно ручное вмешательство** |
+| **Done** | `381a2833...` | Всё задеплоено | Готово |
+| **Cancelled** | `b1cae7f9...` | Отменена | — |
+
+### Переходы статусов
+
+```
+Backlog → [QG-0 pass] → In Progress (analyst запущен)
+In Progress → [analyst questions] → Needs Input
+Needs Input → [Слава ответил] → In Progress (analyst перезапущен)
+In Progress → [analyst done] → In Review (ждёт :approved:)
+In Review → [:approved:] → In Progress (architect запущен)
+In Review → [:rejected:] → In Progress (analyst перезапущен с причиной)
+In Progress → [все этапы до done] → Done
+In Progress → [3 retry исчерпаны / deploy fail] → Blocked
+```
+
+### Комментарии в Plane
+
+Orchestrator автоматически пишет комментарии при:
+- Каждом переходе stage (с ссылками на branch и PR)
+- QG failure (что не прошло и почему)
+- Запуске агента
+- Вопросах analyst'а (текст вопросов)
+- Ошибках (deploy fail, retry exhausted)
+- Завершении задачи
+
+### Ссылки в комментариях
+
+При переходах stage комментарий содержит:
+- 📂 Branch: ссылка на ветку в Gitea
+- 🔗 PR: ссылка на Pull Request (если есть, на этапах review/testing/deploy)
+
+### Webhook events
+
+| Event | Действие |
+|-------|----------|
+| `work_item.created` / `issue.created` | QG-0 → create branch → init docs → launch analyst |
+| `comment.created` / `issue_comment.created` | Проверка `:approved:` / `:rejected:` / ответ на вопросы |
+
+### QG-0: Валидация при создании Issue
+
+При создании Issue в Plane, orchestrator проверяет:
+- Title: 5-80 символов
+- Description: ≥2 предложений
+
+Если не проходит → Issue переходит в **Blocked** + комментарий с описанием что исправить.
+
+---
+
 ## Механизмы автономности

 ### Auto-advance
@@ -85,14 +147,79 @@ created → analysis → architecture → development → review → testing →
 ### Auto-PR
 После developer push, `_ensure_pr()` автоматически создаёт PR в Gitea.

+### Auto-init
+При создании Issue в Plane → webhook → QG-0 → branch → docs → analyst.
+Слава просто создаёт Issue — всё остальное автоматически.
+
 ### Retry (developer)
 При `REQUEST_CHANGES` от reviewer'а — developer перезапускается (до 3 раз).

+### Retry (tester fail)
+При FAIL тестов — developer перезапускается для фикса (до 3 раз).
+После 3 неудач → Issue переходит в **Blocked**.
+
+### Analyst questions
+Analyst может создать `01-questions.md` → Issue переходит в **Needs Input**.
+Слава отвечает комментарием → analyst перезапускается с ответами (до 3 раундов).
+
 ### Notifications
 Telegram уведомления на каждом переходе stage + при ошибках.

 ---

+## Сценарии работы
+
+### 🟢 Позитивный (happy path)
+
+1. Слава создаёт Issue в Plane: "Добавить фильтр по высоте"
+2. QG-0 ✓ → branch `feature/ET-012-filter-altitude` → analyst запущен
+3. Analyst пишет BRD/ТЗ/AC/TestPlan → Issue → **In Review**
+4. Слава читает, пишет `:approved:` → Issue → **In Progress**
+5. Architect → ADR → auto-advance
+6. Developer → код + тесты → PR → auto-advance
+7. Reviewer → APPROVED → auto-advance
+8. Tester → PASS → auto-advance
+9. Deployer → merge → tag → deploy → smoke ✓ → Issue → **Done**
+10. Telegram: "🎉 ET-012: задача завершена!"
+
+### 🟡 Analyst задаёт вопросы
+
+1. Analyst не понимает требования → создаёт `01-questions.md`
+2. Issue → **Needs Input** + Telegram: "❓ ET-012: Analyst задаёт вопросы"
+3. Слава отвечает комментарием в Plane
+4. Orchestrator ловит комментарий → Issue → **In Progress** → analyst перезапущен
+5. Analyst учитывает ответы → пишет ТЗ → Issue → **In Review**
+6. (Максимум 3 раунда вопросов, потом → **Blocked**)
+
+### 🟡 Слава отклоняет ТЗ
+
+1. Issue в **In Review**, Слава пишет `:rejected: Не учтены мобильные устройства`
+2. Issue → **In Progress** → analyst перезапущен с причиной отклонения
+3. Analyst исправляет → Issue → **In Review** (повторно)
+
+### 🔴 Tester находит баги
+
+1. Tester прогоняет тесты → FAIL в `13-test-report.md`
+2. Issue остаётся **In Progress** → developer перезапущен для фикса
+3. Developer фиксит → reviewer → tester (повторно)
+4. Если 3 попытки developer'а не помогли → Issue → **Blocked**
+5. Telegram: "🚨 ET-012: Tests still failing after 3 retries"
+
+### 🔴 Deploy fail
+
+1. Deployer мержит PR, деплоит, smoke test FAIL
+2. Deployer откатывает к предыдущему тегу
+3. Issue → **Blocked**
+4. Telegram: "🚨 ET-012: Deploy failed! Rolled back."
+
+### 🔴 Architect conflict
+
+1. Architect находит конфликт с ТЗ → создаёт `10-conflict.md`
+2. Issue → **In Progress** → analyst перезапущен с описанием конфликта
+3. Analyst пересматривает ТЗ → Issue → **In Review** (повторно)
+
+---
+
 ## Файловая структура

 ```
@@ -100,16 +227,16 @@ Telegram уведомления на каждом переходе stage + пр
 ├── src/
 │   ├── main.py              # FastAPI app
 │   ├── config.py            # Settings (env vars)
-│   ├── db.py                # SQLite (tasks, agent_runs)
+│   ├── db.py                # SQLite (tasks, agent_runs, events)
 │   ├── stages.py            # STAGE_TRANSITIONS
-│   ├── notifications.py     # Telegram + Plane comments
-│   ├── plane_sync.py        # Plane API integration
+│   ├── notifications.py     # Telegram notifications
+│   ├── plane_sync.py        # Plane API (states, comments, links)
 │   ├── agents/
-│   │   ├── launcher.py      # AgentLauncher (AGENT_CONFIGS, launch, monitor)
+│   │   ├── launcher.py      # AgentLauncher (launch, monitor, retry, advance)
 │   │   └── __init__.py
 │   ├── webhooks/
 │   │   ├── gitea.py         # Push, PR, CI status handlers
-│   │   ├── plane.py         # Comment handlers (:approved:)
+│   │   ├── plane.py         # work_item.created, comment handlers
 │   │   └── __init__.py
 │   └── qg/
 │       ├── checks.py        # QG check functions
@@ -126,6 +253,7 @@ Telegram уведомления на каждом переходе stage + пр
 - **Host:** mva154 (82.22.50.71)
 - **Container:** `orchestrator` (port 8500)
 - **Gitea:** localhost:3000 (в docker network)
+- **Plane:** localhost:8091 (в docker network)
 - **Repos:** `/home/slin/repos/orchestrator`, `/repos/enduro-trails` (в контейнере)
 - **DB:** SQLite (`/app/data/orchestrator.db`)
 - **Logs:** `/app/data/logs/` (per-agent run logs)
@@ -137,12 +265,15 @@ Telegram уведомления на каждом переходе stage + пр
 **`:approved:` после analyst'а** — Слава подтверждает ТЗ в Plane.

 Всё остальное — полностью автономно:
+- auto-init при создании Issue
 - architect запускается автоматически после approve
 - developer → после architecture done
 - reviewer → после CI green
 - tester → после review approved
 - deployer → после tests passed
 - done → после deploy success
+- retry при ошибках (до 3 раз)
+- rollback при deploy fail

 ---

@@ -156,6 +287,7 @@ Telegram уведомления на каждом переходе stage + пр
 - Один environment (test), нет prod
 - Нет budget tracking
 - Все агенты на Sonnet (proposal: Architect/Reviewer на Opus)
+- Нет Plane подзадач (7 subtasks) — один Issue, этапы в orchestrator DB

 ---

@@ -169,3 +301,12 @@ Telegram уведомления на каждом переходе stage + пр
 | 2026-05-31 | Add: REQUEST_CHANGES retry logic (3 attempts) |
 | 2026-06-01 | Add: **deployer agent** (merge → tag → deploy → smoke → rollback) |
 | 2026-06-01 | Remove: `_auto_merge_pr` hardcode from `_try_advance_stage` |
+| 2026-06-01 | Add: **Plane states** — Needs Input, In Review, Blocked |
+| 2026-06-01 | Add: **Analyst questions flow** (01-questions.md → Needs Input → relaunch) |
+| 2026-06-01 | Add: **:rejected: handler** с причиной + relaunch |
+| 2026-06-01 | Add: **Tester FAIL → developer retry** (до 3 раз → Blocked) |
+| 2026-06-01 | Add: **Deploy FAIL → Blocked** + rollback |
+| 2026-06-01 | Add: **Architect conflict** (10-conflict.md → rollback to analysis) |
+| 2026-06-01 | Add: **QG-0** валидация при создании Issue |
+| 2026-06-01 | Add: **Ссылки в комментариях** (branch + PR URLs) |
+| 2026-06-01 | Add: **Max 3 question rounds** для analyst |