128 lines
12 KiB
Markdown
128 lines
12 KiB
Markdown
# Статусная модель 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. Предлагаемая статусная модель (итог) — v2 с правками Славы
|
||
|
||
### A. Новые статусы (создать в Plane + замапить в резолвере)
|
||
| Статус | Класс | Группа | Кто ставит/жмёт | Смысл |
|
||
|---|---|---|---|---|
|
||
| **Analysis** | 🔵 выход | started | орк | идёт анализ/BRD (1-я стадия) — СВОЙ статус вместо In Progress |
|
||
| **Awaiting Deploy** | 🔵 выход | started | орк (Phase A) | staging зелёный, merge готов — жду Confirm Deploy на прод |
|
||
| **Confirm Deploy** | 🟢 вход | started | человек | запустить Phase B прод-деплой (УЖЕ создан в ORCH-59 ✅) |
|
||
| **Deploying** | 🔵 выход | started | орк (Phase B) | прод-деплой идёт (detached), health-check |
|
||
| **Monitoring** | 🔵 выход | started | орк (post-deploy ORCH-21) | деплой встал, идёт пост-деплой окно (~15мин, 30 опросов) — ещё НЕ Done |
|
||
|
||
(имена `Awaiting Deploy` / `Monitoring` — рабочие; финал — по ответам Славы, см. §5)
|
||
|
||
### B. Семантика `In Review` — РАЗГРУЗИТЬ
|
||
- Оставить `In Review` ТОЛЬКО за approve-pending артефактов конвейера (BRD/ревью) — исходный смысл.
|
||
- Phase A перестаёт ставить `In Review` → ставит **`Awaiting Deploy`**.
|
||
|
||
### B2. Вход в analysis — РАЗГРУЗИТЬ (пункт 3 Славы)
|
||
- Сейчас: человек жмёт `In Progress` (вход-триггер) → но и стадия `analysis` маппится в
|
||
`in_progress` (`_STAGE_TO_STATE_KEY`), и `deploy` тоже → ТРОЙНАЯ перегрузка `In Progress`.
|
||
- Проблема: задача в анализе висит как «In Progress», не видно ЧТО именно идёт (анализ).
|
||
- Решение: ввести выходной статус **`Analysis`** (по аналогии с Architecture/Development/...).
|
||
`In Progress` остаётся ТОЛЬКО входным триггером «начать конвейер» (человек жмёт), а орк сразу
|
||
переводит в `Analysis`. После ввода Awaiting Deploy/Deploying/Monitoring статус `In Progress`
|
||
больше НЕ используется как индикация стадии — только как кнопка старта. Чисто.
|
||
|
||
### B3. post-deploy monitor → статус `Monitoring` (пункт 1 Славы)
|
||
- Сейчас: после health-OK задача СРАЗУ → Done, а монитор (ORCH-21) тикает «после Done» 15 мин.
|
||
`Done` означает «процесс стартовал», а не «доказанно здоров».
|
||
- Решение: ввести **`Monitoring`** между Deploying и Done. Финалайзер при health-OK ставит
|
||
`Monitoring` (а не Done) → пост-деплой окно тикает → при чистом закрытии (HEALTHY, 30 опросов)
|
||
→ `Done`; при деградации (5xx/UNHEALTHY) → `Blocked` + Telegram + сигнал к откату.
|
||
Тогда `Done` = «развёрнуто И доказанно стабильно 15 минут».
|
||
|
||
### C. Полный жизненный цикл задачи (целевой v2)
|
||
```
|
||
Backlog → Todo → [In Progress*] → Analysis → [In Review → Approved] → Architecture →
|
||
Development → Review → Testing → Awaiting Deploy → [Confirm Deploy] → Deploying →
|
||
Monitoring → Done
|
||
(* In Progress = только кнопка старта, человек; дальше всё ставит орк)
|
||
[...] = действие человека (вход-триггер)
|
||
```
|
||
Ветки: Rejected (откат), Needs Input (нужен ввод), **Blocked (затык/поломка/фейл деплоя)**, Cancelled.
|
||
|
||
### D. Гигиена — ИСПРАВЛЕНО по факту кода
|
||
- **`Blocked` — НЕ убирать, он РАБОЧИЙ** (проверено grep'ом, был неправ ранее). Код ставит
|
||
`set_issue_blocked` в 9+ местах: фейл гейтов, retry-cap, бюджет исчерпан (anti-livelock),
|
||
БАГ-8 rollback (deploy→development), падение агента (launcher), reconciler Guard 2 пропускает
|
||
blocked-задачи. Именно его Слава видел при поломках. Несущий статус — ОСТАВИТЬ.
|
||
Доп.выгода новой модели: фейл деплоя `Deploying`/`Monitoring` → `Blocked` (консистентно).
|
||
- **Разгрузка `In Progress`:** см. B2 — станет чисто входным триггером.
|
||
- `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. Открытые вопросы Славе (v2)
|
||
1. **Имя approve-pending деплоя:** `Awaiting Deploy` или `Ready for Deploy`? (склоняюсь к
|
||
`Awaiting Deploy` — «жду тебя»; `Ready for Deploy` = «готово к деплою», тоже ясно).
|
||
2. **Имя пост-деплой статуса:** `Monitoring` / `Monitoring after Deploy` / `Post-Deploy Watch` /
|
||
`Verifying`? (склоняюсь к `Monitoring` — коротко; `Verifying` подчёркивает «проверяю здоровье»).
|
||
3. **Фейл деплоя `Deploying`/`Monitoring` → куда?** Предлагаю **`Blocked`** (консистентно с тем,
|
||
как код уже метит фейлы) + Telegram + сигнал к откату на rollback-снимок. Согласен?
|
||
4. **`Analysis` статус** для 1-й стадии — вводим (как просил, п.3)? Да/нет.
|
||
5. **Оформить как work item** эпика ORCH-54 (напр. `ORCH-XX-status-model`)? Сейчас или после ORCH-23?
|
||
|
||
### Сводка новых статусов к созданию в Plane (после согласования имён):
|
||
`Analysis`, `Awaiting Deploy`, `Deploying`, `Monitoring` (+ `Confirm Deploy` уже есть).
|
||
`Blocked` — остаётся. `In Review` — разгружается (только артефакты). `In Progress` — только старт.
|