111 lines
8.0 KiB
Markdown
111 lines
8.0 KiB
Markdown
# 01 — Business Requirements Document (BRD)
|
||
|
||
**Work Item:** ORCH-066
|
||
**Заголовок:** [высокий] Статусная модель Plane: осмысленные статусы этапов
|
||
**Стадия:** analysis
|
||
**Автор:** Analyst
|
||
**Дата:** 2026-06-07
|
||
|
||
---
|
||
|
||
## 1. Контекст и проблема
|
||
|
||
Статусная модель Plane оркестратора имеет **семантические перегрузки**: один и тот
|
||
же Plane-статус используется для несовместимых смыслов, из-за чего:
|
||
|
||
- оператор не понимает, на каком реально этапе стоит задача (доска нечитаема);
|
||
- повышается риск ошибки оператора (например, неверный ручной перевод статуса);
|
||
- `In Progress` одновременно означает «человек запускает конвейер», «идёт анализ»,
|
||
«идёт прод-деплой» и «возврат из Needs Input» — четыре разных смысла на одном статусе.
|
||
|
||
Уже частично исправлено: ORCH-059 ввёл отдельный статус для подтверждения деплоя
|
||
(`Confirm Deploy`), разгрузив перегруженный `Approved`. ORCH-066 завершает наведение
|
||
порядка по **утверждённой Owner** статусной модели.
|
||
|
||
### Два слоя (критично различать)
|
||
|
||
| Слой | Что это | Источник | Трогаем? |
|
||
|------|---------|----------|----------|
|
||
| **A** | `STAGE_TRANSITIONS` — внутренняя машина стадий (`created→analysis→…→done`) | `src/stages.py` | **НЕТ (инвариант)** |
|
||
| **B** | Plane-статусы — индикация на доске | `src/plane_sync.py` + точки в `src/stage_engine.py` / `src/webhooks/plane.py` | **ДА** |
|
||
|
||
ORCH-066 меняет **только слой B** и точки, где код вручную проставляет Plane-статусы.
|
||
|
||
---
|
||
|
||
## 2. Целевая статусная модель (решение Owner)
|
||
|
||
```
|
||
Backlog → Todo → [To Analyse] → Analysis → [In Review → Approved] → Architecture →
|
||
Development → Code-Review → Testing → Awaiting Deploy → [Confirm Deploy] → Deploying →
|
||
Monitoring after Deploy → Done
|
||
```
|
||
|
||
- `[...]` = **действие человека** (вход-триггер).
|
||
- Остальное ставит **орк** (индикация).
|
||
|
||
### Ветки (нелинейные исходы)
|
||
- **Rejected** — откат на предыдущую стадию (человек).
|
||
- **Needs Input** — ТОЛЬКО аналитик (НЕ расширять на других агентов).
|
||
- **Blocked** — затык / фейл деплоя / деградация прода.
|
||
- **Cancelled** — человек решил не делать задачу (валидный выход из In Review).
|
||
|
||
---
|
||
|
||
## 3. Бизнес-требования
|
||
|
||
| ID | Требование | Приоритет |
|
||
|----|------------|-----------|
|
||
| **BR-1** | Каждый этап конвейера показывается на доске Plane осмысленным статусом (To Analyse / Analysis / Code-Review / Awaiting Deploy / Deploying / Monitoring after Deploy). | Must |
|
||
| **BR-2** | `To Analyse` — единый человеческий вход: (а) старт нового конвейера, (б) resume/relaunch аналитика при возврате из Needs Input. Заменяет роль `In Progress` как входа-триггера. | Must |
|
||
| **BR-3** | Стадия `analysis` индицируется отдельным статусом `Analysis` (орк ставит при старте/relaunch аналитика), а не `In Progress`. | Must |
|
||
| **BR-4** | Стадия `review` индицируется Plane-статусом `Code-Review` (переименование `Review`). | Must |
|
||
| **BR-5** | Self-deploy Phase A (approval-pending) ставит `Awaiting Deploy` вместо `In Review`. | Must |
|
||
| **BR-6** | Self-deploy Phase B (старт прод-деплоя) ставит `Deploying`. | Must |
|
||
| **BR-7** | Self-deploy Phase C (health-OK финализация) ставит `Monitoring after Deploy` (НЕ `Done` сразу). | Must |
|
||
| **BR-8** | Post-deploy monitor (ORCH-021): чистое закрытие окна (HEALTHY) → `Done`; UNHEALTHY/деградация → `Blocked`. | Must |
|
||
| **BR-9** | `In Review` разгрузить: оставить ТОЛЬКО за approve-pending артефактов конвейера (BRD/ревью). Выходы: `Approved` (вперёд), `Rejected` (откат), `Cancelled` (человек отменил). | Must |
|
||
| **BR-10** | `Needs Input` — БЕЗ ИЗМЕНЕНИЙ. Остаётся только у аналитика (`01-questions.md` → `set_issue_needs_input`). Механизм не трогать. | Must |
|
||
| **BR-11** | Возврат аналитика из Needs Input выполняется через `To Analyse` (а НЕ через `In Progress`). Логика fork «старт vs resume» (по наличию task + active-job) сохраняется. | Must (грабли R1) |
|
||
| **BR-12** | **Fail-closed:** отсутствие нового статуса в проекте (enduro / Plane API down / fallback `_DEFAULT_STATES`) НЕ приводит к падению; поведение остаётся backward-compatible (паттерн ORCH-059 AC-7). | Must |
|
||
| **BR-13** | Reconciler не «оживляет» активные ожидания (`Awaiting Deploy` / `Deploying` / `Monitoring after Deploy`) как зависшие задачи (Guard 2 skip-list). | Must |
|
||
| **BR-14** | Документация (golden source) обновлена в том же PR: `CLAUDE.md`, `docs/architecture/README.md`, `CHANGELOG.md`, ADR per-work-item. | Must |
|
||
|
||
---
|
||
|
||
## 4. Границы (Out of Scope / НЕ трогать)
|
||
|
||
- `STAGE_TRANSITIONS` (`src/stages.py`) — машина стадий, инвариант.
|
||
- `QG_CHECKS`, `check_deploy_status`, exit-коды хука (0/1/2), merge-gate, схема БД.
|
||
- `Confirm Deploy` (уже работает, ORCH-059).
|
||
- Механизм `Needs Input` (analyst-only) — не расширять, не менять.
|
||
- Поведение прод-деплоя **не-self** репозиториев (enduro-trails): для них терминальный
|
||
переход остаётся `deploy → Done` как сейчас (Monitoring after Deploy не применяется —
|
||
post-deploy monitor армится только для self-hosting).
|
||
- Автоматический approve / авто-rollback self-hosting (ORCH-54 / ORCH-021 политика
|
||
ALERT_ONLY) — не меняется.
|
||
|
||
---
|
||
|
||
## 5. Инфра-предусловие (вне кода, делает оператор)
|
||
|
||
Новые Plane-статусы в проекте **ORCH** создаёт оператор через Plane API **ДО** эксплуатации:
|
||
`To Analyse`, `Analysis`, `Code-Review`, `Awaiting Deploy`, `Deploying`,
|
||
`Monitoring after Deploy` (`Confirm Deploy` уже есть).
|
||
|
||
Резолвер (`_PLANE_NAME_TO_KEY` + `get_project_states`) подхватывает их **по имени** с
|
||
**fail-closed fallback** на `_DEFAULT_STATES` (см. BR-12). Документируется в
|
||
`07-infra-requirements.md` (создаёт архитектор) и в `docs/operations/`.
|
||
|
||
---
|
||
|
||
## 6. Definition of Done
|
||
|
||
- Plane показывает осмысленные статусы на каждом этапе.
|
||
- Возврат аналитика из Needs Input работает через `To Analyse`.
|
||
- Phase A → `Awaiting Deploy`, Phase B → `Deploying`, Phase C → `Monitoring after Deploy`,
|
||
окно HEALTHY → `Done`, фейл → `Blocked`.
|
||
- `STAGE_TRANSITIONS` не изменён.
|
||
- `pytest tests/ -q` — зелёный. Fail-closed покрыт тестами.
|
||
- Документация обновлена.
|