auto-sync: 2026-06-07 22:50:01

tasks/orchestrator/STATUS_MODEL_PROPOSAL.md

@@ -0,0 +1,99 @@
+# Статусная модель Plane для оркестратора — ревизия и предложение
+
+Дата: 2026-06-07 · Автор: Стрим · Статус: **предложение на согласование со Славой**
+
+## 0. Зачем
+Сегодня всплыли две семантические перегрузки статусов (оба = риск ошибки оператора):
+1. **`Approved`** значил И «BRD принят, продолжай» И «ВЫКАТИ В ПРОД» → починили в ORCH-59
+   (ввели `Confirm Deploy`).
+2. **`In Review`** ставится И на approve-pending BRD (ранние стадии) И на approve-pending
+   прод-деплоя (Phase A). Оператор видит `In Review` и не понимает: это «посмотри артефакт»
+   или «жду твоего Confirm Deploy на прод». ← **боль, которую заметил Слава.**
+
+Плюс: нет отдельного статуса «идёт внедрение» (между Confirm Deploy и Done задача
+визуально «прыгает» сразу в Done, момент реального деплоя на доске не виден).
+
+## 1. Как код РЕАЛЬНО работает со статусами (факты из репо)
+
+### Статусы, которые ЧИТАЕТ webhook (`handle_issue_updated`) — это ВХОД от человека:
+- `In Progress` → старт/перезапуск стадии
+- `Approved` → advance стадии (BRD-гейт) + РАНЬШЕ триггерил прод (теперь нет)
+- `Confirm Deploy` → Phase B прод-деплой (ORCH-59, новый)
+- `Rejected` → откат на пред. стадию
+- **Всё остальное** (In Review, Needs Input, Blocked, Done, доски-стадии) — **код ИГНОРИРУЕТ
+  на входе**, это статусы, которые орк ставит САМ (выход).
+
+### Статусы, которые орк СТАВИТ сам (это ВЫХОД, индикация прогресса):
+- Per-stage доски: `Architecture / Development / Review / Testing` (видимость стадии)
+- `In Progress` (analysis, deploy), `In Review` (approve-pending), `Needs Input`, `Done`
+
+### Ключевой инсайт для модели
+Статусы делятся на ДВА класса, и их нельзя мешать:
+- **🟢 ВХОД (человек → орк, триггеры):** In Progress, Approved, Rejected, **Confirm Deploy**
+- **🔵 ВЫХОД (орк → доска, индикация):** Architecture/Development/Review/Testing,
+  In Review, Needs Input, Done, (Blocked)
+
+Перегрузка возникала, когда один статус был и входом, и выходом, ИЛИ один вход значил два
+действия. Цель модели — чтобы **каждый триггер = ровно один смысл**.
+
+## 2. Предложение Славы (разбор)
+1. **«approve-pending деплоя пусть будет не `In Review`, а `Ready for Deploy`»** — ✅ ДА.
+   Сейчас Phase A ставит `In Review` (перегруз с BRD-ревью). Нужен отдельный выходной статус.
+   Предлагаю имя **`Awaiting Deploy`** (или `Ready for Deploy`) — «всё зелёно, жду твой
+   Confirm Deploy на прод». Семантика: орк выставил → человек видит «пора жать Confirm Deploy».
+2. **«нужен статус "идёт внедрение", после успеха → Done»** — ✅ ДА.
+   Предлагаю **`Deploying`** — орк ставит при старте Phase B (detached прод-деплой идёт),
+   снимает в Done после health-OK финалайзера (или в Rejected/Blocked при фейле).
+
+## 3. Предлагаемая статусная модель (итог)
+
+### A. Новые статусы (создать в Plane + замапить в резолвере)
+| Статус | Класс | Группа | Кто ставит/жмёт | Смысл |
+|---|---|---|---|---|
+| **Awaiting Deploy** | 🔵 выход | started | орк (Phase A) | staging зелёный, merge готов — жду Confirm Deploy на прод |
+| **Confirm Deploy** | 🟢 вход | started | человек | запустить Phase B прод-деплой (УЖЕ создан в ORCH-59 ✅) |
+| **Deploying** | 🔵 выход | started | орк (Phase B) | прод-деплой идёт (detached), health-check в процессе |
+
+### B. Семантика `In Review` — РАЗГРУЗИТЬ
+- Оставить `In Review` ТОЛЬКО за approve-pending артефактов конвейера (BRD/ревью на ранних
+  стадиях) — это его исходный смысл.
+- Phase A перестаёт ставить `In Review` → ставит **`Awaiting Deploy`**.
+
+### C. Полный жизненный цикл задачи (целевой)
+```
+Backlog → Todo → In Progress(analysis) → [In Review → Approved] → Architecture →
+Development → Review → Testing → Awaiting Deploy → [Confirm Deploy] → Deploying → Done
+                                                         (человек)     (орк)
+```
+Ветки: Rejected (откат), Needs Input (нужен ввод), Blocked (затык), Cancelled.
+
+### D. Что УБРАТЬ / признать лишним (гигиена)
+Кандидаты на чистку (проверить, что нигде в коде не читаются как триггер):
+- **`Blocked`** — код его не выставляет и не читает как триггер (есть в маппинге, но не в
+  жизненном цикле). Либо начать использовать осмысленно (затык внешней зависимости), либо убрать.
+- **Дубль индикации:** `In Progress` используется и для analysis, и для deploy-стадии
+  (STAGE_TO_STATE). После ввода Awaiting Deploy/Deploying стадия deploy получит свои статусы —
+  In Progress останется только за analysis. Чище.
+- Проверить `Todo` vs `Backlog` — оба «не начато»; возможно один лишний (низкий приоритет).
+
+## 4. Объём изменений (для будущего ТЗ Dev-агенту)
+- **Plane (инфра, делаю я через API):** создать `Awaiting Deploy`, `Deploying`
+  (`Confirm Deploy` уже есть). Удаление лишних — после подтверждения.
+- **Код (Dev-агент):**
+  - `src/plane_sync.py`: добавить ключи `awaiting_deploy`, `deploying` в `_DEFAULT_STATES`/
+    `_PLANE_NAME_TO_KEY`; новый хелпер `set_issue_awaiting_deploy`, `set_issue_deploying`.
+  - `src/stage_engine.py` Phase A: `set_issue_in_review` → `set_issue_awaiting_deploy`.
+  - `src/stage_engine.py`/`self_deploy.py` Phase B: при старте деплоя ставить `Deploying`;
+    финалайзер при health-OK → `Done`, при фейле → `Rejected`/`Blocked`.
+  - webhook: `Awaiting Deploy`/`Deploying` остаются ИГНОРируемыми на входе (они выходные).
+  - Документация: CLAUDE.md (статусная модель), architecture/README, CHANGELOG, ADR.
+  - Тесты: Phase A ставит Awaiting Deploy (не In Review); Phase B ставит Deploying;
+    fail-closed при отсутствии статусов.
+
+## 5. Открытые вопросы Славе
+1. Имя для approve-pending деплоя: **`Awaiting Deploy`** или **`Ready for Deploy`**? (склоняюсь
+   к `Awaiting Deploy` — подчёркивает «жду тебя», но `Ready for Deploy` тоже ок).
+2. При фейле прод-деплоя `Deploying` → куда? Предлагаю **`Rejected`** (откат на deploy, повторный
+   Confirm Deploy после фикса) — консистентно с текущим rollback. Или отдельный `Deploy Failed`?
+3. `Blocked` — начать использовать (внешний затык) или убрать как мёртвый?
+4. Оформить как work item эпика ORCH-54 (например ORCH-60-status-model)? Делать после ORCH-23?