# 02 — ТЗ: выделенный статус «Confirm Deploy» как триггер прод-деплоя

Work Item: **ORCH-059** · Repo: `orchestrator` · Stage: analysis

> ТЗ описывает **что** должно измениться и **поведенческий контракт**. Конкретный
> дизайн (сигнатуры, способ проброса признака «confirm-deploy» из webhook в
> `stage_engine`, sentinel-обработка) — за архитектором (ADR per-work-item).
> Точки касания ниже заданы бизнес-запросом Owner и текущей реализацией ORCH-036.

## 1. Задействованные модули `src/`

| Модуль | Роль в задаче |
|--------|---------------|
| `src/plane_sync.py` | Резолвер состояний Plane. Добавить логический ключ `confirm_deploy` ↔ имя статуса «Confirm Deploy»; обеспечить безопасный доступ при отсутствии статуса (fallback/неполный конфиг). |
| `src/webhooks/plane.py` | `handle_issue_updated` — маршрутизация нового статуса; `handle_verdict` — отделить «подтверждение деплоя» от обычного approve; снять триггер Фазы B со статуса `Approved` на `deploy`. |
| `src/stage_engine.py` | Блок Фазы B (`current_stage == "deploy" and finished_agent is None`) должен срабатывать ТОЛЬКО по сигналу confirm-deploy, не по обычному Approved. Обновить CTA-текст Фазы A (`_handle_self_deploy_phase_a`). |
| `src/config.py` | (опционально, на усмотрение архитектора) флаг/имя статуса, если потребуется конфигурируемость. По умолчанию — не требуется. |

## 2. Поведенческий контракт (требования)

### TRZ-1. Регистрация статуса «Confirm Deploy»
Резолвер состояний (`get_project_states`) обязан возвращать UUID статуса
«Confirm Deploy» под логическим ключом `confirm_deploy` для проекта ORCH.
Маппинг имени `"Confirm Deploy" → "confirm_deploy"` добавляется в
`_PLANE_NAME_TO_KEY`. Для проектов/сред, где статус отсутствует (enduro,
fallback `_DEFAULT_STATES`, недоступный API), ключ может отсутствовать —
обращение к нему должно быть **fail-closed**: «нет статуса → ветка confirm-deploy
не активируется», без `KeyError`/исключения.

### TRZ-2. Триггер прод-деплоя по «Confirm Deploy»
Когда задача находится на стадии `deploy` и issue переводится в статус
`Confirm Deploy`, система обязана инициировать **Фазу B** прод-деплоя
(эквивалент текущего `_handle_self_deploy_phase_b`: idempotency-guard `initiated`,
`self_deploy.initiate_deploy`, постановка `deploy-finalizer`, комментарии/Telegram).
Поведение, идемпотентность и Фаза C — **без изменений** относительно ORCH-036;
меняется только **что именно является триггером**.

### TRZ-3. `Approved` больше не запускает прод-деплой
Перевод задачи стадии `deploy` в статус `Approved` **не должен** инициировать
Фазу B. Он не должен также вызывать ложный откат (БАГ-8) или ложный advance
по `check_deploy_status` (вердикта ещё нет). Допустимое поведение — **no-op с
логированием** (issue остаётся на `deploy`/approval-pending). Конкретный способ
(игнор на уровне webhook-роутинга или на уровне `stage_engine`) — за архитектором.

### TRZ-4. Сохранность гейта `Approved` на остальных стадиях
Статус `Approved` обязан продолжать работать как человеческий гейт:
- `analysis` → `architecture` (`check_analysis_approved`, approved-via-status);
- любой иной человеческий approve-advance, существующий сегодня.
Регрессия `handle_verdict(approved=True)` для НЕ-`deploy` стадий недопустима.

### TRZ-5. CTA Фазы A
Текст запроса approve в `_handle_self_deploy_phase_a` (Plane-комментарий + Telegram)
обязан инструктировать оператора переводить задачу в статус **`Confirm Deploy`**
(а не `Approved`) для запуска прод-деплоя.

### TRZ-6. Условность (как ORCH-35/36)
Ветка confirm-deploy реальна только для self-hosting
(`self_deploy.self_deploy_applies(repo)` → `orchestrator`). Для прочих репо —
прежнее поведение (синхронный деплой агентом), статус `Confirm Deploy` не
требуется и не влияет.

## 3. Изменения API
Изменений HTTP-эндпоинтов **нет**. Канал — существующий `POST /webhook/plane`
(событие `work_item.updated`). Внешнее изменение: в проекте ORCH появляется
дополнительный статус доски «Confirm Deploy» (Plane-конфигурация, не код-API).

## 4. Изменения схемы БД
**Нет.** `STAGE_TRANSITIONS`, реестр `QG_CHECKS`, таблицы `tasks`/`jobs`/
`agent_runs`/`events` — без изменений. Статусы — на стороне Plane; restart-safe
состояние деплоя — существующие sentinel-файлы ORCH-036 (без миграций).

## 5. Требования к новым QG checks
**Нет.** Новый Quality Gate не вводится. `check_deploy_status` /
`_parse_deploy_status` и контракт exit-кодов хука (0/1/2) — без изменений.

## 6. Конфигурация среды (предусловие эксплуатации)
- В проекте ORCH в Plane создаётся статус доски **«Confirm Deploy»** (точное имя,
  чувствительно к регистру — должно совпасть с ключом `_PLANE_NAME_TO_KEY`).
- Размещение статуса на доске — рядом со стадией deploy/approval-pending
  (рекомендация эксплуатации, не код).
- Кэш состояний (`get_project_states` / `reload_project_states`): после создания
  статуса может потребоваться сброс кэша или рестарт по штатной стадии deploy.

## 7. Артефакты, создаваемые/обновляемые по pipeline
- `docs/work-items/ORCH-059/06-adr/ADR-001-confirm-deploy-status.md` — решение
  (как отличается триггер; где разрезается перегрузка `Approved`; fail-closed
  при отсутствии статуса) — **ведёт архитектор**.
- `CLAUDE.md` — упоминание выделенного статуса approve прод-деплоя (раздел
  self-hosting / артефакты).
- `docs/architecture/README.md` — секция ORCH-036: уточнить, что Фаза B
  триггерится статусом `Confirm Deploy`, а не `Approved`.
- `CHANGELOG.md` — запись ORCH-059.
- `12-review.md`, `13-test-report.md`, `14-deploy-log.md`, `15-staging-log.md` —
  штатно по стадиям конвейера.

## 8. Совместимость и инварианты
- Не меняются: `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_deploy_status`,
  БАГ-8 (FAILED → откат на development), merge-gate, exit-коды хука, Фазы A/C,
  схема БД, post-deploy (ORCH-021).
- Self-hosting safety: правка НЕ требует внепланового рестарта прод-контейнера;
  выкат — через штатный deploy-staging (8501) → deploy.
- Never-crash: отсутствие статуса `Confirm Deploy` в резолвере не приводит к
  исключению в webhook-пути.