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.

8.7 KiB Raw Blame History Unescape Escape