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

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-пути.