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