---
work_item: ORCH-027
stage: architecture
author_agent: architect
status: proposed
created_at: 2026-06-10
model_used: claude-opus-4-8
---

# 07 — Инфраструктурные требования: ORCH-027 — Code coverage как гейт

Work Item: **ORCH-027** · Repo: **orchestrator** · Стадия: architecture

> When-applicable. Топология **не меняется** (всё в существующем Docker-контейнере на одном
> сервере mva154, SQLite, собственная очередь). Затрагивается только зависимостный и
> конфигурационный слой.

## Топология / окружение

- **Без изменений топологии** — никаких новых контейнеров/сервисов/нод. Гейт исполняется внутри
  существующего процесса оркестратора, измерение — в per-branch worktree (`ensure_worktree`),
  как merge-gate re-test. `docs/operations/INFRA.md` — без правок.
- **Self-hosting безопасность (NFR-3):** гейт не вызывает деплой-хук, не рестартит прод-контейнер
  `orchestrator` (8500), не пушит в `main`. Прод-деплой ORCH-027 — **только** через
  staging-гейт (8501) → выделенный статус «Confirm Deploy» (ORCH-059), без рестарта прод
  случайным approve.

## Зависимости

| Зависимость | Где | Назначение |
|-------------|-----|-----------|
| `pytest-cov` (обёртка `coverage.py`) | `requirements.txt` | измерение line coverage прогоном `pytest --cov=src --cov-report=json`. Offline (сеть при измерении не нужна). Попадает в прод-образ при пересборке. |

- Версия фиксируется совместимой с текущим `pytest` (см. `requirements.txt`/`pytest.ini`).
- Новых системных пакетов в `Dockerfile` не требуется (чистый pip-пакет).

## Конфигурация (env, `.env` на хосте)

Новые флаги (`config.py`, префикс `ORCH_COVERAGE_*`; дефолты безопасны — нулевая регрессия):

| Env | Дефолт | Назначение |
|-----|--------|-----------|
| `ORCH_COVERAGE_GATE_ENABLED` | `false` (раскат поэтапный) | kill-switch |
| `ORCH_COVERAGE_GATE_REPOS` | пусто → только self-hosting | CSV область применения |
| `ORCH_COVERAGE_MIN_PERCENT` | консервативно (напр. backstop) | абсолютный порог-floor |
| `ORCH_COVERAGE_POLICY` | `both` | `absolute\|baseline\|both` |
| `ORCH_COVERAGE_EPSILON` | малый (напр. `0.5`) | допуск на шум измерения |
| `ORCH_COVERAGE_TOOL_FAIL_CLOSED` | `false` | поведение при сбое инструмента |
| `ORCH_COVERAGE_RUN_TIMEOUT_S` | по образцу `merge_retest_timeout_s` | тайм-аут прогона |

## Эксплуатационные предусловия

- **Bootstrap базовой линии:** при первом merge применимого репо базовая линия `main`
  засевается автоматически фактическим измеренным покрытием (D5). Ручной первичный замер не
  обязателен; при необходимости — `POST /coverage/baseline?repo=orchestrator&value=<%>` (D8).
- **Раскат:** включать `ORCH_COVERAGE_GATE_ENABLED=true` только после прод-деплоя кода и
  прогона на staging (8501); стартовая область — только `orchestrator`.
- **Override (легитимное снижение покрытия):** `POST /coverage/baseline` (по образцу
  `POST /serial-gate/unfreeze`) либо временный `ORCH_COVERAGE_POLICY=absolute`.

## Секреты / сеть

- Новых секретов нет. Сетевого доступа при измерении нет (coverage offline).
- enduro-trails и прочие репозитории — вне области по умолчанию, нулевое влияние.