# 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 покрыт тестами.
- Документация обновлена.