# 01 — BRD: BUG — deploy-staging петля (откат deploy-staging → development) для self-deploy

Work Item: **ORCH-061**
Тип: **BUG**
Приоритет: **P0**
Репозиторий: `orchestrator` (self-hosting)
Эпик-контекст: блокер **ORCH-54** (автономное внедрение self-hosting)

---

## 1. Резюме (Executive summary)

На стадии `deploy-staging` для self-hosting репозитория `orchestrator` задача
зацикливается: гейт ребра `deploy-staging → deploy` даёт FAILED, `stage_engine`
откатывает задачу `deploy-staging → development`, developer-агент перезапускается,
проходит конвейер заново, снова упирается в `deploy-staging`, снова откат — и так
по кругу (с расходом developer-ретраев и кредитов LLM), либо до исчерпания лимита
ретраев и блокировки.

Следствие: **прод-деплой self-hosting репо невозможен автономно**. Последние
ORCH-задачи (ORCH-58, ORCH-60) доводились до прода **вручную** (ручной merge PR +
ручной build-once retag + ручной `--deploy`). Это прямой блокер автономного
внедрения (эпик ORCH-54).

## 2. Бизнес-контекст и проблема

Оркестратор дорабатывает сам себя (self-hosting). Стадия `deploy-staging`
(порт 8501) — обязательная страховка перед прод-деплоем орка (ORCH-35, ADR-0003).
На этой стадии deployer гоняет `scripts/staging_check.py` против живого
staging-стенда и пишет машинный вердикт `staging_status: SUCCESS|FAILED` в
`15-staging-log.md`. Гейт `check_staging_status` читает этот вердикт; `FAILED`
→ откат на `development` (ORCH-35, `_handle_qg_failure_rollbacks`).

Подтверждены **две независимые причины** зацикливания.

### Причина №1 — ложный FAILED `check_staging_status` (контекст ORCH-58)

`staging_check.py` в sandbox-прогоне даёт **8/10 PASS, 2 ложных FAIL** на e2e-блоке
Block C:
- **C9a** — ветка не появляется в `orchestrator-sandbox` (branch not found);
- **C9b** — analyst-job не появляется в staging-очереди (`/queue → recent`).

Сопутствующая пометка suite: «Plane comment check skipped: bot-tokens not added to
SANDBOX project» — bot-аккаунты агентов (`ORCH_PLANE_BOT_*`) не добавлены членами
SANDBOX-проекта Plane (проект создан после провижининга ботов). Это **отсутствие
sandbox-настроек инфраструктуры, а не регресс кода**. Тем не менее `staging_check.py`
возвращает ненулевой exit-code → deployer пишет `staging_status: FAILED` → гейт
FAILED → откат `deploy-staging → development`.

### Причина №2 — «no changes to commit» на action-стадии (контекст ORCH-60)

Стадии деплоя по своей природе **действие, а не правка кода** (рестарт/retag), и
закономерно не порождают git-изменений в `src/`/`tests/`. Сигнал «no changes»
для action-стадии не должен трактоваться как недовыполнение работы; критерий успеха
action-стадии — успешное выполнение действия (exit0 + доказанный health/staging),
а не наличие нового коммита. Сейчас отсутствие изменений на стадии деплоя приводит
к недопродвижению задачи и откату.

### Совокупный эффект

Любая из причин по отдельности достаточна, чтобы зациклить self-deploy. Обе
проявились на реальных задачах ORCH-58 и ORCH-60, которые пришлось доводить вручную.

## 3. Цели (Goals)

- **G1.** ORCH-задача для self-hosting `orchestrator` проходит
  `deploy-staging → deploy → done` **без ручного вмешательства** и **без петли**.
- **G2.** Ложный (инфраструктурный) FAIL `staging_check` в sandbox **не вызывает**
  откат `deploy-staging → development`.
- **G3.** Отсутствие git-изменений на стадиях деплоя (`deploy-staging` / `deploy`)
  **не трактуется** как недовыполнение и не приводит к откату.
- **G4.** Реальный регресс (настоящий провал staging-проверки или прод-деплоя)
  **по-прежнему** приводит к откату `→ development` (страховка не ослабляется).

## 4. Вне области (Non-goals)

- Полная автоматизация ручного approve прод-деплоя (это ORCH-54).
- Изменение конвейера стадий (`STAGE_TRANSITIONS`), реестра гейтов как структуры,
  контрактов `check_deploy_status` / `check_staging_status` frontmatter-вердиктов.
- Изменение поведения для **не**-self-hosting репозиториев (enduro-trails и пр.):
  для них staging-гейт и self-deploy остаются no-op / прежними.
- Изменение схемы БД.

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

| Роль | Интерес |
|------|---------|
| Owner / оператор оркестратора | Автономный self-deploy без ручных шагов и без ночных петель. |
| Другие проекты (enduro-trails) | Их конвейер не должен быть затронут (общий инстанс, общая очередь). |
| Агенты (deployer) | Чёткий, не ложно-срабатывающий контракт стадии деплоя. |

## 6. Кандидатные направления решения (из бизнес-запроса)

Бизнес-запрос называет два направления (одно или оба); **выбор и механизм —
за архитектором (ADR)**, BRD требует лишь достижения G1–G4:

- **(а)** Сделать sandbox-прогон `staging_check` честным (например, настроить
  bot-токены SANDBOX Plane-проекта / починить sandbox e2e), чтобы C9a/C9b
  проходили честно (10/10) и `check_staging_status` не падал ложно.
- **(б)** Отвязать продвижение стадий деплоя от git-changes для self-deploy:
  успех action-стадии = exit0 + health/staging PASS, а не наличие коммита.

## 7. Бизнес-эффект / риски бездействия

- **Эффект:** разблокировка автономного внедрения self-hosting (ORCH-54);
  устранение ручного труда (merge + retag + deploy) и риска ошибки при ручных шагах.
- **Риск бездействия:** каждая ORCH-задача требует ручного дотягивания до прода;
  петли жгут кредиты LLM и developer-ретраи, задачи блокируются.

## 8. Допущения

- Прод-контейнер `orchestrator` (8500) обслуживает все проекты из общего инстанса —
  его **нельзя** ронять/перезапускать в рамках задачи (см. CLAUDE.md, INFRA.md).
- Изменения касаются self-hosting пути (`is_self_hosting_repo` / `self_deploy_applies`);
  для прочих репо поведение не меняется.
- Документация — golden source: затронутые `docs/architecture/README.md`,
  `docs/operations/STAGING_CHECK.md`, `CHANGELOG.md` обновляются в том же PR.