---
type: review
work_item_id: ORCH-088
verdict: APPROVED
version: 1
---

# Review ORCH-088 — Per-repo serial gate (Этап 1, serial e2e)

## Summary
PR реализует per-repo serial gate (FR-1…FR-5) тремя согласованными механизмами в полном
соответствии с ТЗ и ADR-001: gate-в-claim (`db.claim_next_job`), отложенный срез ветки
(`start_pipeline` → `launcher._materialize_deferred_branch`) и durable rollback-freeze
(`repo_freeze` + `POST /serial-gate/unfreeze`). Чистая логика вынесена в leaf-модуль
`src/serial_gate.py` (never-raise). Полный прогон `pytest tests/ -q` — **1114 passed**;
профильные сюиты (`test_serial_gate*`, `test_queue_endpoint`, `test_plane_webhook`,
`test_status_trigger`) — 33 passed. Документация обновлена в том же PR. Блокеров нет.

## Оси проверки

### 1. Соответствие ТЗ / AC
- FR-1 (gate на входе в анализ) — gate-фрагмент в `claim_next_job`, только `jobs.agent='analyst'`,
  только локальная БД (NFR-2). AC-1 ✓
- FR-2 (очередь e2e, FIFO) — реализация уточняет псевдо-SQL ADR `t2.id != jobs.task_id` на
  `t2.id < jobs.task_id`. Уточнение **корректно и обосновано** (при `!=` пакет одновременно
  созданных задач взаимно блокируется → дедлок); задокументировано в коде, CHANGELOG и README.
  AC-2 ✓
- FR-3 (per-repo) — все выборки фильтруются `t2.repo = jobs.repo`; cross-repo параллелизм
  сохранён. AC-4 ✓
- FR-4 (restart-safe) — активная задача из `tasks`, freeze в `repo_freeze`; in-memory состояния
  нет. AC-3 ✓
- FR-5 (rollback-freeze) — `set_repo_freeze` в DEGRADED-ветке `run_post_deploy_monitor` +
  Telegram-алерт; ручное снятие `POST /serial-gate/unfreeze`. AC-5 ✓
- AC-6 (анти-stale-base) — закрыт **структурно**: ветка не создаётся до открытия gate
  (deferred cut в `_materialize_deferred_branch` от свежего `origin/main`). ✓
- AC-7 (kill-switch/нулевая регрессия), AC-8 (fail-OPEN claim), AC-9 (fail-CLOSED freeze),
  AC-10 (`/queue` блок), AC-11 (инварианты) — все подтверждены кодом и тестами.

### 2. Соответствие ADR
- D1–D10 реализованы как описано. Единственное отклонение — FIFO-условие `<` вместо `!=`
  (D1) — улучшает ADR, устраняет дедлок, явно задокументировано. Глобальный ADR
  `adr-0017-serial-gate.md` заведён и зарегистрирован.
- `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / merge-gate / merge-verify / image-freshness /
  post-deploy / exit-коды хука — без изменений (AC-11). ✓

### 3. Качество кода
- Leaf-модуль `src/serial_gate.py` — строгий never-raise; корректно разнесены направления
  отказа: claim — fail-OPEN (`build_claim_clause` → `""`), freeze — fail-CLOSED
  (`is_repo_frozen` → `True`). Санитизация repo-токенов `^[A-Za-z0-9._-]+$` перед встраиванием
  в SQL `IN (...)`.
- Миграция `repo_freeze` аддитивна и идемпотентна (`CREATE TABLE/INDEX IF NOT EXISTS`).
- `_materialize_deferred_branch` исполняется в worker-потоке (нет running loop) → `asyncio.run`
  безопасен; Gitea-вызовы идемпотентны (409/422 → no-op) → реклейм/рестарт безопасны; transient
  Gitea-ошибка пробрасывается → job переочередь (нет half-cut состояния).
- Docstrings содержательны на всех публичных функциях.

### 4. Качество тестов
Содержательные сюиты покрывают gate (claim), deferred branch, e2e, freeze, `/queue`-snapshot,
webhook и status-trigger. Тесты не тривиальны (проверяют поведение, а не факт вызова).

## Findings

### P0 — Blocker
- (нет)

### P1 — Must fix
- (нет)

### P2 — Should fix
- (нет — отмечено лишь как наблюдение) `_materialize_deferred_branch` делает два отдельных
  `asyncio.run` подряд; функционально корректно, можно объединить в один loop при будущем
  рефакторинге. Не блокирует.

## Документация
Обновлена в том же PR — правило golden-source (CLAUDE.md §2) выполнено:
- `docs/architecture/README.md` — новый раздел «Per-repo serial gate (ORCH-088)», обновлены
  таблица API (`GET /queue` + новый `POST /serial-gate/unfreeze`), раздел БД (`repo_freeze`),
  строка статуса доработок.
- `CLAUDE.md` — абзац о serial-режиме в разделе «Очередь задач».
- `CHANGELOG.md` — запись `feat:` (ORCH-088).
- `.env.example` — три новых флага с описанием.
- `docs/work-items/ORCH-088/06-adr/ADR-001-serial-gate.md` + сквозной
  `docs/architecture/adr/adr-0017-serial-gate.md` + `08-data-requirements.md`.

Изменения `src/` полностью отражены в документации → требование Reviewer §4 удовлетворено.