# ADR-001 (ORCH-021): Post-deploy мониторинг прода + реакция на деградацию

## Статус
Proposed (design) — реализация в ветке `feature/ORCH-021-post-deploy-rollback`.
Сквозной индексный ADR: `docs/architecture/adr/adr-0010-post-deploy-monitor.md`.
Помечено `arch:major-change` (новая под-компонента + новый reserved-agent job-kind).

## Контекст
Конвейер заканчивается на `deploy → done` (`check_deploy_status` видит
`deploy_status: SUCCESS` → terminal-sync, Plane → Done, release merge-lease). После
этого оркестратор **забывает про прод**. «Успех» сегодня = прохождение health-check
в момент рестарта (10×6с в `scripts/orchestrator-deploy-hook.sh`) — узкое окно ~60с.

Класс инцидентов «зелёный деплой, красный прод» (прецедент **ET-8**): деградация
проявляется через минуты под боевым трафиком (прогрев кэшей, фоновые миграции,
утечки, рост 5xx), health отвечает `200 ok`, но фича сломана. Для self-hosting это
критично: сломанный прод-орк (8500) обслуживает ВСЕ проекты из общего инстанса.

BRD/ТЗ задают требования (BR-1…BR-11, AC-1…AC-18) и оставляют архитектору **три
открытых вопроса** (BRD §7): (1) где живёт наблюдение — стадия / watchdog-daemon /
reserved-agent job; (2) механизм self-rollback; (3) пороги/веса сигналов.

Существующие переиспользуемые механики:
- **deploy-finalizer** (ORCH-36, `stage_engine.run_deploy_finalizer` + перехват в
  `launcher.launch_job` ДО `_spawn`) — детерминированный no-LLM reserved-agent job,
  само-перепостановка через `enqueue_job(available_at_delay_s=...)`, defer-budget,
  restart-safe (jobs-очередь + sentinel-файлы `.deploy-state-<repo>/<wi>/`).
- **self_deploy.py** — sentinel-state хелперы (`write_marker`/`has_marker`/
  `read_result`/`clear_state`), detached host-процесс (`build_deploy_command`/
  `initiate_deploy`: ssh + setsid), `map_exit_code_to_status`, `self_deploy_applies`.
- **reconciler.py** — daemon-поток + `status()` в `GET /queue`.
- **хук `--rollback`** (`do_rollback`): retag `PREV_IMAGE_FILE` → `TARGET_IMAGE` +
  рестарт + health, коды 0 / 1 (нет prev-образа) / 2 (rollback тоже упал).
- **Условность** ORCH-35/36/43/58: `is_self_hosting_repo`, флаг + CSV-репо.

## Решение

### 1. Механизм наблюдения — reserved-agent job `post-deploy-monitor` (Вариант B)
Наблюдение реализуется как **детерминированный no-LLM reserved-agent job**, точная
калька **deploy-finalizer**. Один «тик» наблюдения = один job: он делает ОДИН опрос
сигналов, обновляет персистентные счётчики в sentinel-файлах, классифицирует и либо
**перепостанавливает себя** с задержкой `post_deploy_interval_s` (окно не истекло и
ещё не DEGRADED), либо завершает наблюдение (DEGRADED → реакция; либо окно истекло →
HEALTHY). Это «watchdog поверх очереди»: между тиками job не выполняется (он
запланирован в будущем через `available_at_delay_s`), worker свободен для других
проектов — ровно как defer у finalizer.

**Почему НЕ daemon-watchdog (Вариант A, как reconciler):** daemon тикает глобально, а
не per-task; серию опросов (последовательные провалы health, доля 5xx на окне) пришлось
бы держать в памяти → теряется/двоится при рестарте (а сам деплой орка = рестарт). Чтобы
сделать daemon restart-safe, всё равно нужны персистентные per-task счётчики в sentinel —
тогда reserved-agent проще и уже имеет проверенную restart-safe машинерию (jobs-очередь
+ `requeue_running_jobs` + sentinels). Per-task жизненный цикл естественно ложится на
job-цепочку, а не на глобальный sweep.

**Почему НЕ отдельная пост-deploy стадия (Вариант C):** меняет `STAGE_TRANSITIONS` +
реестр `QG_CHECKS` (нарушает AC-12, ТЗ §2.8 — явно непредпочтительно); ломает семантику
`deploy → done` как терминального перехода (Plane уже Done). Наблюдение происходит
**ПОСЛЕ** `done` — «продление ответственности ЗА done», а не новая стадия конвейера.

### 2. Арм наблюдения — хук в terminal-блоке `advance_stage`
В `stage_engine.advance_stage`, в существующем блоке `next_stage == "done"` (после
`set_issue_done` и `release_merge_lease`), добавляется арм:
```
if next_stage == "done" and post_deploy.post_deploy_applies(repo):
    post_deploy.arm_monitor(repo, work_item_id, branch, task_id)
```
`arm_monitor` (never-raise): если sentinel `armed` отсутствует → создаёт state-dir,
пишет `armed` (идемпотентность, по образцу `INITIATED`), инициализирует `series`-файл,
ставит первый `post-deploy-monitor` job через `enqueue_job(available_at_delay_s=
post_deploy_interval_s)`. Если `armed` уже есть → no-op (двойной webhook / reconciler
F-1 / finalizer Phase C могут довести `done` повторно — AC-15). Выключенный
kill-switch / неприменимый репо → `post_deploy_applies` False → арма нет (AC-2/AC-10).

### 3. Чистая логика — новый leaf-модуль `src/post_deploy.py` (never-raise)
По образцу `self_deploy.py` / `staging_verdict.py`. Импортирует только config (+lazy
`qg.checks.is_self_hosting_repo`), НЕ импортирует `stage_engine`/`launcher`. Функции:
- **`post_deploy_applies(repo) -> bool`** — флаг `post_deploy_monitor_enabled` +
  CSV `post_deploy_repos` (пусто → только self-hosting). Калька `self_deploy_applies`.
- **`probe_signals(base_url) -> ProbeResult`** — один опрос: `GET /health` (HTTP 200 +
  `{"status":"ok"}`) и ключевые эндпоинты `/status`, `/queue` (учёт доли 5xx).
  Сеть/таймаут → консервативный «провал»-результат, не исключение.
- **`classify(series, fail_threshold, 5xx_threshold) -> "HEALTHY"|"DEGRADED"`** —
  чистая, без сети, **главный предмет юнит-тестов** (детерминированная, как
  `compute_staging_verdict`): `DEGRADED` если `≥ fail_threshold` ПОСЛЕДОВАТЕЛЬНЫХ
  провалов health (AC-4) ИЛИ доля 5xx на окне `> 5xx_threshold` (AC-5). Иначе
  `HEALTHY` (одиночный провал < порога с восстановлением → HEALTHY, AC-3/AC-6).
- **`decide_action(repo, verdict) -> "NONE"|"ROLLBACK"|"ALERT_ONLY"`** — чистая:
  `HEALTHY → NONE`; `DEGRADED` + self-hosting → `ALERT_ONLY` (BR-5/AC-8, ВСЕГДА);
  `DEGRADED` + не-self + `post_deploy_auto_rollback=True` → `ROLLBACK`; иначе →
  `ALERT_ONLY`.
- **Sentinel-state хелперы** (state-dir `.post-deploy-state-<repo>/<wi>/`, по образцу
  `self_deploy._state_dir`): `armed`, `series` (JSON-список результатов опросов,
  append каждый тик — restart-safe счётчики), `done`. `read_series`/`append_probe`/
  `mark_done`/`has_marker` — never-raise.
- **`write_post_deploy_log(...)`** — артефакт `16-post-deploy-log.md`, best-effort
  (по образцу `self_deploy.write_deploy_log`).
- **`build_rollback_command(repo)`** — argv хука `--rollback` с прод-env (как
  `build_deploy_command`, но action=`--rollback`; переиспользует `deploy_prod_*`).

### 4. Исполнение тика — `stage_engine.run_post_deploy_monitor(job)` + перехват в launcher
По образцу `run_deploy_finalizer` / `_run_deploy_finalizer_job`:
`launcher.launch_job` перехватывает `agent == "post-deploy-monitor"` ДО `_spawn` →
`stage_engine.run_post_deploy_monitor(job)`. Алгоритм тика (never-raise):
1. `mark_done` уже стоит → no-op (AC-15, защита от дубля).
2. `probe = post_deploy.probe_signals(base_url)`; `append_probe(series, probe)`.
3. `verdict = classify(series, ...)`.
4. **Если `HEALTHY` и окно не истекло** (число тиков < `window_s/interval_s`) →
   перепостановка `post-deploy-monitor` через `available_at_delay_s=interval_s`
   (как finalizer defer; счётчик тиков — из jobs-очереди/`series`, restart-safe).
5. **Если `HEALTHY` и окно истекло** → исход `NONE`, `write_post_deploy_log(HEALTHY,
   NONE)`, `mark_done`, нотификация «окно завершилось чисто» (BR-6/AC-17).
6. **Если `DEGRADED`** → `action = decide_action(...)`; исполнить реакцию (§5),
   `write_post_deploy_log`, `mark_done`, нотификации.

`mark_done` + sentinel `armed` дают идемпотентность; jobs-очередь +
`requeue_running_jobs` + `series` дают restart-safe (AC-15). Бюджет тиков bounded
(`window_s/interval_s`) — анти-livelock, как `deploy_finalize_max_attempts`.

### 5. Реакция на деградацию
- **Self-hosting (`orchestrator`), всегда (BR-5/AC-8):** `ALERT_ONLY`. НЕ откатывать
  и НЕ рестартить прод-контейнер в тике. Громкий Telegram + Plane-коммент с запросом
  ручного approve отката (по образцу deploy Phase A CTA). `action_taken: ALERT_ONLY`.
  Откат самого прод-орка (если оператор решит) — ТОЛЬКО через detached host-процесс
  (контейнер не откатит себя, умирая); переиспользуется механика
  `self_deploy.initiate_deploy`, но в MVP она вне тика наблюдения (ручной approve →
  отдельный путь, как ORCH-54 для авто-deploy). Тик self НИКОГДА не запускает хук
  `--rollback` (структурный инвариант).
- **Не-self + `post_deploy_auto_rollback=True` (AC-7):** вызвать хук `--rollback` с
  прод-env (`build_rollback_command`). Маппинг exit-code по смыслу
  `map_exit_code_to_status`: `0 → ROLLBACK_OK`; `1/2 → ROLLBACK_FAILED` + громкий
  Telegram о необходимости ручного вмешательства (AC-9). Целевой контейнер не есть
  orchestrator → его рестарт безопасен для конвейера.
- **Не-self + auto_rollback=False (дефолт):** `ALERT_ONLY`.

### 6. Артефакт `16-post-deploy-log.md` (новый, машиночитаемый)
YAML-frontmatter (канон гейтов; для петли уроков ORCH-8, BR-10):
```
---
post_deploy_status: HEALTHY | DEGRADED
action_taken: NONE | ROLLBACK_OK | ROLLBACK_FAILED | ALERT_ONLY
work_item: <plane-id>
window_s: <int>
checks_total: <int>
checks_failed: <int>
---
```
Тело — человекочитаемая сводка опросов. Best-effort (отсутствие файла ничего не роняет,
AC-13). **Не** читается ни одним гейтом — наблюдение происходит после `done`.

### 7. Конфигурация — `src/config.py` (env-префикс `ORCH_`)
- `post_deploy_monitor_enabled: bool = True` — глобальный kill-switch (BR-8/AC-10).
- `post_deploy_repos: str = ""` — CSV применимых репо; пусто → только self-hosting.
- `post_deploy_window_s: int = 900` — окно наблюдения (~15 мин, BR-1).
- `post_deploy_interval_s: int = 30` — интервал опросов.
- `post_deploy_fail_threshold: int = 3` — N послед. провалов health → DEGRADED.
- `post_deploy_5xx_threshold: float = 0.5` — порог доли 5xx → DEGRADED.
- `post_deploy_auto_rollback: bool = False` — глоб. разрешение авто-отката (для self
  всегда требует approve, BR-5).
- `post_deploy_base_url: str = "http://localhost:8500"` — наблюдаемый прод.
- Параметры отката — переиспользовать существующие `deploy_prod_*` (новых дублей нет).

### 8. Наблюдаемость — блок `post_deploy` в `GET /queue` (BR-9/AC-14)
По образцу блока `reconcile` (метод `status()`): `enabled`, `window_s`, `interval_s`,
активные наблюдения (по sentinel `armed` без `done`), последний исход
(`post_deploy_status`/`action_taken`). Best-effort, never-raise.

### Инварианты (НЕ меняются)
`STAGE_TRANSITIONS`, реестр `QG_CHECKS`, `check_deploy_status`/`_parse_deploy_status`,
момент вердикта `deploy_status`, БАГ-8 откат, terminal-sync `deploy → done`, merge-gate,
exit-code-контракт хука (0/1/2), схема БД. Условность как ORCH-35/36/43/58. Never-raise
во всём наблюдении (AC-16). Тик self НИКОГДА не рестартит прод-контейнер (AC-8).

## Альтернативы
- **Daemon-watchdog (как reconciler)** — отклонён: per-task серия в памяти не
  restart-safe; restart-safe-вариант требует тех же sentinel-счётчиков → reserved-agent
  проще и уже проверен.
- **Отдельная пост-deploy стадия + QG** — отклонён: меняет реестры (AC-12), ломает
  семантику терминального `done`; наблюдение принципиально ПОСЛЕ `done`.
- **Авто-rollback прод-орка из тика** — отклонён (BR-5): контейнер не откатит себя
  надёжно; групповой риск для всех проектов. Self → только ALERT + ручной approve.
- **Новая колонка в `tasks` для отметки наблюдения** — отклонён: миграция на проде
  (риск, как в adr-0007); sentinel-файлы достаточны и restart-safe (как ORCH-36/53/58).
- **Прометей/APM** — вне рамок (BR out-of-scope): опираемся на существующие
  HTTP-эндпоинты, не вводим сбор метрик.

## Последствия
- Класс «зелёный деплой, красный прод» закрыт измеримыми порогами; деградация —
  машиночитаемый сигнал для петли уроков (ORCH-8).
- Плюс: максимальное переиспользование проверенной finalizer/sentinel/hook-машинерии;
  нулевая миграция БД; реестры не тронуты; дефолты безопасны (auto-rollback off, self
  только alert).
- Минус/ограничение: монитор self бежит ВНУТРИ наблюдаемого прод-контейнера — если
  контейнер полностью wedged, worker может не выполнить тик и алерта не будет (gap).
  Это known limitation MVP; внешний независимый watchdog — follow-up (вне рамок).
- Минус: каждый тик на короткое время занимает single-worker (`max_concurrency=1`);
  митигируется коротким опросом (~секунды) и `interval_s` между тиками (defer не держит
  worker), как finalizer.
- Доменный smoke результата фичи (BR-11) — follow-up; MVP = health + 5xx.

## Связи
- **ET-8** — обоснование (deploy SUCCESS, прод не работает).
- **adr-0007-executable-self-deploy** (ORCH-36) — sentinel-паттерн, detached
  host-процесс, `map_exit_code_to_status`, deploy-finalizer reserved-agent (образец).
- **adr-0007-reconciler** (ORCH-53) — daemon/`status()` образец (рассмотрен и отклонён
  как основной механизм; `status()`-снимок в `/queue` переиспользуется).
- **adr-0006-merge-gate** / **adr-0003-staging-gate** — образец условности и флагов
  раската (`*_enabled` + `*_repos`).
- **adr-0008-staging-image-provenance** — `.deploy-prev-image` / хук-механика отката.
- **ORCH-8** — петля уроков (потребитель `16-post-deploy-log.md`).
- **ORCH-54** — будущий полный авто (включая авто-approve отката self), по аналогии
  с авто-deploy.
