118 lines
8.4 KiB
Markdown
118 lines
8.4 KiB
Markdown
# 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.
|