# BRD — ORCH-36: Исполняемый самодеплой (стадия deploy дёргает хост-хук, Вариант B)

Work Item: ORCH-036
Stage: analysis
Автор: analyst
Дата: 2026-06-06

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

Стадия `deploy` конвейера сейчас **«бумажная»**. На ней deployer-агент (LLM) только
пишет `docs/work-items/<wi>/14-deploy-log.md` с `deploy_status: SUCCESS|FAILED`, а QG
`check_deploy_status` (`src/qg/checks.py:464`) парсит этот вердикт и пускает `deploy → done`.
**Реального docker-деплоя нет** — продакшен орка катается руками (Стрим).

Хост-хук `scripts/orchestrator-deploy-hook.sh` **уже существует** (ORCH-34) и умеет:
захват PREV_IMG → `git pull` → рестарт сервиса → health-check (10×6с = 60с) →
авто-rollback при провале health, с корректным exit-code. Дефолты — STAGING-безопасные;
прод включается через override env (`TARGET_SERVICE`, `TARGET_PORT`, `TARGET_IMAGE`,
`COMPOSE_PROFILE`).

**Главная мина (self-hosting):** прод-контейнер `orchestrator` (8500) — ОДИН на все
проекты, и в нём же бежит сам deployer-агент. Deployer не может синхронно рестартить
контейнер, в котором живёт (`docker compose up -d orchestrator` убьёт его процесс на
середине). Реальный рестарт self-репо обязан делать ВНЕШНИЙ хост-хук (вне контейнера),
который срабатывает ПОСЛЕ выхода агента. Рубильник — снаружи; орк только ИНИЦИИРУЕТ.

## 2. Цель

Превратить стадию `deploy` в РЕАЛЬНЫЙ самодеплой: после зелёного `deploy-staging`-гейта
конвейер вызывает хост-хук с прод-параметрами, хук промоутит образ в прод (8500) с
health-чеком и авто-rollback. Результат хука (exit-code) маппится в `deploy_status`.
**На старте — с ОБЯЗАТЕЛЬНЫМ ручным approve** (`DEPLOY_REQUIRE_MANUAL_APPROVE=true`):
прод не трогается без явного «go» Владельца.

## 3. Ценность для бизнеса

- Уходит последний ручной шаг конвейера (прод-деплой Стрим) → шаг к автономному внедрению (эпик ORCH-54).
- `deploy_status: SUCCESS` становится **доказанным** (реальный health-ok), а не декларацией LLM.
- Гарантия build-once: «что протестировали на staging — то и в проде» (тот же образ, без пересборки).
- Прод никогда не остаётся в нерабочем состоянии: авто-rollback + health-таймаут.

## 4. Заинтересованные стороны

| Роль | Интерес |
|------|---------|
| Владелец (Слава/Стрим) | Контроль через ручной approve; уведомления о каждом промоуте/откате |
| Проект enduro-trails | Прод-орк не должен падать (общий инстанс) — групповой риск |
| Конвейер ORCH | Стадия `deploy` исполняемая, гейты не сломаны |

## 5. Объём (scope)

### В объёме
1. Исполнение реального прод-деплоя из стадии `deploy` через хост-хук (ssh / detached на хосте).
2. Обязательный ручной approve-гейт ПОСЛЕ зелёного staging и ДО прод-рестарта (флаг включён).
3. Маппинг exit-code хука → `deploy_status: SUCCESS|FAILED` (реальный, не бумажный).
4. Уведомления (Plane-коммент + Telegram) на каждый промоут и откат.
5. Build-once: перетегирование образа, прошедшего staging, без пересборки.
6. Обновление `deployer.md` и `INFRA.md` (документация = golden source).
7. Для НЕ-self репо (enduro-trails и др.) — деплой по ssh на их хост (поведение не ломается).

### Вне объёма (явно)
- **Включение полного авто** (`DEPLOY_REQUIRE_MANUAL_APPROVE: true → false`) — отдельная задача,
  ТОЛЬКО после набора метрик доверия (см. §7). В этой задаче флаг НЕ выключается.
- Изменение `docker-compose.yml` без явной необходимости.
- Изменение стадий `STAGE_TRANSITIONS`, реестра QG, terminal-sync `deploy → done`.
- Прод-деплой в реальный бой во время разработки задачи (отладка — только на staging-цели хука).

## 6. Бизнес-требования

- **BR-1.** После зелёного `deploy-staging`-гейта стадия `deploy` РЕАЛЬНО собирает/перетегирует
  образ, рестартит целевой сервис и проверяет health — не пишет бумажный SUCCESS.
- **BR-2.** Для self-репо `orchestrator` рестарт 8500 выполняется ВНЕШНИМ (detached/host)
  процессом; deployer-агент НЕ убивает контейнер, в котором работает.
- **BR-3.** `deploy_status: SUCCESS` пишется ТОЛЬКО при health-ok хука; провал/health-fail →
  `deploy_status: FAILED` → откат на `development` (как ORCH-35 staging-rollback, БАГ-8).
- **BR-4.** Ручной approve обязателен (флаг `true`): без явного «go» прод НЕ трогается.
- **BR-5.** Каждый промоут и откат уведомляет Владельца: Plane-коммент в задачу + Telegram.
  «Молчаливых» деплоев нет.
- **BR-6.** Build-once: в прод идёт тот образ, что прошёл staging-гейт (перетег, не пересборка).
- **BR-7.** Staging-гейт (`check_staging_status`) остаётся обязательным предусловием прод-деплоя.
- **BR-8.** Прод никогда не остаётся в нерабочем состоянии — авто-rollback при провале health.
- **BR-9.** Существующие гейты и инварианты не ломаются: `check_deploy_status`,
  `_parse_deploy_status`, rollback `deploy → development` (БАГ-8), terminal-sync `deploy → done`,
  merge-gate (ORCH-43).
- **BR-10.** Документация (`deployer.md`, `INFRA.md`, `CHANGELOG.md`) обновлена в том же PR.

## 7. Критерии готовности к включению ПОЛНОГО авто (вне этой задачи)

Переключать `DEPLOY_REQUIRE_MANUAL_APPROVE: true → false` можно ТОЛЬКО когда закрыты ВСЕ 5:
1. ≥10 успешных промоутов подряд (staging зелёный → approve → прод поднялся, откат не нужен).
2. Zero false-negative: staging-гейт ни разу не пропустил битый деплой как «зелёный».
3. Авто-rollback проверен в бою (≥2–3 реальных срабатывания), recovery 100%, MTTR < 60с.
4. Ни одного «молчаливого» деплоя (каждый промоут/откат уведомил Владельца).
5. Период наблюдения ≥10 деплоев ИЛИ ≥2 недели без инцидентов в режиме manual-approve.

## 8. Риски

| Риск | Влияние | Митигация |
|------|---------|-----------|
| Падение прод-орка 8500 при self-деплое | Встаёт конвейер ВСЕХ проектов | Detached host-хук + health + авто-rollback; отладка на staging-цели |
| Deployer рестартит сам себя синхронно | Процесс агента убит на середине | BR-2: рестарт только внешним detached-процессом |
| Преждевременный `deploy_status: SUCCESS` (хук ещё не закончил) | Задача уходит в done при незавершённом деплое | Гейт читает РЕАЛЬНЫЙ исход хука (механизм — на дизайне) |
| Деплой без approve | Неконтролируемый прод-деплой | BR-4: approve-гейт блокирует до «go» |
| Пересборка вместо перетега | В прод уезжает не то, что тестировали | BR-6: build-once, `--no-build` + retag |

## 9. Связанные задачи
ORCH-7 (self-hosting), ORCH-21 (auto-rollback), ORCH-34 (хук готов), ORCH-35 (staging-гейт),
ORCH-43 (merge-gate в проде), ORCH-54 (эпик автономного внедрения).
Дизайн-референс: `tasks/orchestrator/DESIGN_STAGING_ENV.md §4/§7`.