# 01 — BRD: Approve прод-деплоя через выделенный статус «Confirm Deploy»

Work Item: **ORCH-059**
Repo: `orchestrator`
Stage: analysis
Тип: enhancement / risk-reduction (self-hosting)

## 1. Контекст и проблема

В ORCH-036 («исполняемый самодеплой стадии `deploy`») прод-деплой self-hosting
инстанса (контейнер `orchestrator`, порт 8500) запускается **Фазой B**: человек
переводит issue в Plane-статус **`Approved`**, webhook
`work_item.updated` → `handle_issue_updated` → `handle_verdict(approved=True)`
→ `_try_advance_stage` → `advance_stage(finished_agent=None)`, и в
`stage_engine.advance_stage` срабатывает блок
`current_stage == "deploy" and finished_agent is None` →
`_handle_self_deploy_phase_b` → detached host-деплой прода.

**Перегрузка статуса.** Тот же самый Plane-статус `Approved` (UUID
`a519a341-…`) используется как **человеческий гейт одобрения BRD** на ранней
стадии `analysis` (`check_analysis_approved`: analysis → architecture) и в общем
verdict-роутинге `handle_verdict`. Один и тот же визуальный «Approved» на доске
означает две принципиально разные вещи:

- на `analysis` — «BRD/ТЗ/AC приняты, продолжай конвейер» (дёшево, обратимо);
- на `deploy` — «**ВЫКАТИ В ПРОД** инструмент, который прямо сейчас обслуживает
  все проекты из одного инстанса с общей БД» (дорого, групповой риск, см.
  раздел Self-hosting в `CLAUDE.md`).

### Последствия (Pain)
- **Двусмысленность семантики.** Один статус — два смысла; оператор не видит из
  названия, что клик на `deploy` запускает реальный прод-рестарт.
- **Риск случайного клика.** Привычный жест «Approved» (которым оператор
  штатно одобряет BRD десятки раз) на стадии `deploy` молча триггерит
  прод-деплой. Цена ошибки — незапланированный рестарт прод-инстанса,
  встающий конвейер всех проектов.
- **Несоответствие ожиданиям ORCH-036.** В scope ORCH-36 заявлялась Telegram
  inline-кнопка подтверждения; в коде её **нет** — developer реализовал approve
  исключительно через Plane-статус. Отдельного «осознанного» жеста подтверждения
  деплоя в системе сейчас не существует.

## 2. Решение Owner

Ввести **отдельный Plane-статус `Confirm Deploy`** в проекте ORCH, который
триггерит **ТОЛЬКО** Фазу B self-deploy на стадии `deploy`. Статус `Approved`
перестаёт запускать прод-деплой и сохраняет единственный смысл — человеческое
одобрение на гейтах конвейера (прежде всего BRD на `analysis`).

Минимальная правка: `handle_verdict` в `src/webhooks/plane.py` + регистрация
нового состояния в проекте ORCH (Plane + резолвер состояний).

## 3. Бизнес-цели
- **BG-1.** Убрать двусмысленность: жест «запустить прод-деплой» отделён от жеста
  «одобрить артефакт».
- **BG-2.** Снизить риск случайного прод-деплоя: запуск прода требует явного,
  редко используемого статуса `Confirm Deploy`, а не привычного `Approved`.
- **BG-3.** Не сломать работающий self-hosting конвейер при доработке самого
  инструмента (нулевая регрессия `analysis`-гейта и не-self репозиториев).

## 4. Объём (Scope)

### В объёме
- Новый логический статус `confirm_deploy` («Confirm Deploy») в резолвере
  состояний Plane (`src/plane_sync.py`).
- Маршрутизация нового статуса в `src/webhooks/plane.py`
  (`handle_issue_updated` / `handle_verdict`) на путь Фазы B прод-деплоя.
- Прекращение триггера Фазы B по статусу `Approved` на стадии `deploy`.
- Обновление текста CTA Фазы A (Plane-комментарий + Telegram в
  `stage_engine._handle_self_deploy_phase_a`): инструктировать оператора
  переводить задачу в `Confirm Deploy`, а не в `Approved`.
- Конфигурация Plane: создание статуса «Confirm Deploy» в проекте ORCH
  (предусловие эксплуатации — фиксируется в TRZ/AC как требование среды).
- Обновление документации (`CLAUDE.md`, `docs/architecture/README.md` секция
  ORCH-036, `CHANGELOG.md`) и ADR per-work-item.

### Вне объёма
- Telegram inline-кнопки подтверждения деплоя (отдельная задача; здесь не
  реализуем — управление по-прежнему статусом Plane).
- Полностью автоматический approve деплоя (ORCH-54).
- Изменение Фаз A/C, exit-кодов хука, merge-gate, `check_deploy_status`,
  схемы БД, реестров `STAGE_TRANSITIONS` / `QG_CHECKS`.
- Поведение прод-деплоя для не-self репозиториев (остаётся прежним).
- Post-deploy наблюдение (ORCH-021) — не затрагивается.

## 5. Заинтересованные стороны
- **Owner/оператор** — переводит задачи по статусам; главный выгодоприобретатель
  снижения риска.
- **Self-hosting конвейер** — все проекты на общем инстансе; косвенно зависят от
  безопасности прод-деплоя орка.

## 6. Допущения
- A-1. Plane позволяет добавить кастомный статус «Confirm Deploy» в проект ORCH;
  его UUID резолвится через `get_project_states` (API `/states/`).
- A-2. Статус `Confirm Deploy` нужен только проекту ORCH (self-hosting). Прочие
  проекты прод-деплой через Plane-approve не используют
  (`self_deploy_applies` → только `orchestrator`).
- A-3. Оператор переводит задачу в `Confirm Deploy` только когда она реально
  находится на стадии `deploy` (approval-pending после Фазы A).

## 7. Риски (детально — 10-tech-risks.md, ведёт архитектор)
- R-1. Новый логический ключ `confirm_deploy` отсутствует в fallback
  `_DEFAULT_STATES` и в проектах без этого статуса → обращение к ключу должно
  быть безопасным (fail-closed: нет статуса → нет деплоя, не падение).
- R-2. Регрессия: `Approved` на `deploy` после правки не должен НИ
  запускать деплой, НИ вызывать ложный откат/advance.
- R-3. Самоправка прода: правка не должна потребовать ручного рестарта прод-
  контейнера вне штатной стадии deploy-staging → deploy.

## 8. Definition of Done (бизнес-уровень)
- Перевод задачи стадии `deploy` в `Confirm Deploy` запускает прод-деплой
  (Фаза B) ровно так же, как раньше делал `Approved`.
- Перевод задачи стадии `deploy` в `Approved` прод-деплой НЕ запускает.
- `Approved` на `analysis` (и прочих человеческих гейтах) работает без изменений.
- CTA Фазы A просит `Confirm Deploy`.
- Документация и ADR обновлены в том же PR.