86 lines
5.7 KiB
Markdown
86 lines
5.7 KiB
Markdown
---
|
||
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 удовлетворено.
|