analyst(ET): auto-commit from analyst run_id=333

docs/work-items/ORCH-059/02-trz.md

@@ -0,0 +1,103 @@
+# 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-пути.