---
verdict: APPROVED
work_item: ORCH-027
stage: review
author_agent: reviewer
status: approved
created_at: 2026-06-10
model_used: claude-opus-4-8
type: review
work_item_id: ORCH-027
version: 2
---

# Review ORCH-027 — Code coverage как гейт

## Summary

Дисциплинированная реализация детерминированного coverage-гейта строго по образцу
security/merge/image-freshness под-гейтов. Соответствие ТЗ/ADR — полное; код качественный,
тесты содержательны (`test_coverage_gate.py` — 30 тестов; **полный регресс `tests/ -q`
зелёный: 1466 passed**); документация обновлена исчерпывающе.

**Единственный прежний блокер закрыт.** Ревизия v1 выносила P1 за повреждённую (дословно
продублированную) запись ORCH-095 в `CHANGELOG.md` — коммит `75c33ab docs(changelog): repair
duplicated ORCH-095 entry body` устранил дубль: тело bullet ORCH-095 теперь присутствует ровно
один раз (`git revert occurrences on line 16: 1`), артефакт чужой задачи восстановлен. Новых
P0/P1 не выявлено.

Проверено: 4 оси (ТЗ / ADR / качество кода / документация) + трассировка маркеров + полный
прогон тест-сьюта.

## Findings

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

### P1 — Must fix
- (нет) — прежний P1 (дубль записи ORCH-095 в CHANGELOG) исправлен коммитом `75c33ab`.

### P2 — Should fix
- [ ] **Несоответствие формулировки ADR-001 D7 фактическому артефакту: 6-польная схема 52c
  не эмитится.** `ADR-001-coverage-gate.md` D7 утверждает: «Артефакт несёт **аддитивно**
  обязательную 6-польную схему 52c, не трогая `coverage_status:`». Фактически и генератор
  (`coverage_gate.render_coverage_report`), и скелет `docs/_templates/18-coverage-report.md`
  эмитят только `coverage_status`/`work_item` + coverage-поля; отсутствуют 5 из 6 полей схемы
  52c (`stage`/`author_agent`/`status`/`created_at`/`model_used`). **Почему не блокер:** (а)
  TRZ §6 формулирует это условно («*Если* отчёт несёт обязательную 6-польную схему 52c —
  добавить её аддитивно»), (б) валидация схемы warning-only по умолчанию
  (`frontmatter_validation_strict=False`), (в) гейт-генерируемые артефакты (прецедент
  `17-security-report.md`) исторически несут лишь свой machine-key — эпик 52c (ORCH-077)
  скоупил схему на 6 агент-промптов, не на машинные отчёты. Машинный вердикт читается из
  `coverage_status:` корректно, контракт не нарушен. **Действие (на усмотрение, не блокирует
  приёмку):** привести формулировку D7 к факту (отчёт несёт `coverage_status:` + coverage-поля,
  без полной 52c-схемы) ЛИБО добавить 5 полей в генератор+шаблон.

## Документация

**Статус: обновлена исчерпывающе** (golden source синхронизирован в том же PR, AC-10 PASS):

- `docs/architecture/README.md` — реестр `QG_CHECKS` дополнен `check_coverage_gate (ORCH-027)`;
  добавлен раздел «Coverage-гейт: защита от деградации покрытия» (точка/порядок, измерение,
  чистая функция, baseline+ratchet, условность/fail-open, артефакт/наблюдаемость). ✅
- `docs/_standards/PIPELINE_DOCS.md` — диапазон доков `…18-coverage-report.md`; строка карты
  `стадия→агент→документ→гейт→machine-key` + строка таблицы вердикт-парсеров
  (`coverage_status:` → `check_coverage_gate`). ✅
- `docs/_templates/18-coverage-report.md` — скелет с frontmatter зарегистрирован. ✅
- `docs/work-items/ORCH-027/06-adr/ADR-001-coverage-gate.md` (D1…D8) +
  сквозной `docs/architecture/adr/adr-0029-coverage-gate.md`. ✅
- `CHANGELOG.md` — детальная корректная запись ORCH-027; повреждение соседней записи ORCH-095
  устранено (v1-P1 закрыт). ✅
- `CLAUDE.md` — паспортный блок «Гейт покрытия тестами (ORCH-027)» добавлен. ✅
- `.env.example` / `src/config.py` — флаги `ORCH_COVERAGE_*` задокументированы. ✅
- Маркеры `ORCH-027` проставлены в коде/доках (AC-10). ✅

`src/` изменён → документация обновлена в том же PR: **да** (P0-условие выполнено).
**Обзорные доки (ORCH-079):** PR не закрывает ни один пункт `README.md` «Известные ограничения»
(coverage-деградация там не значилась) → обновление витрины не требуется, finding отсутствует.

## Оси проверки (детально)

**1. Соответствие ТЗ (02-trz / 03-acceptance) — PASS.**
AC-1 измерение инструментально (`measure_coverage` → `pytest --cov=src` → `totals.percent_covered`,
`pytest-cov==5.0.0` в `requirements.txt`); AC-2 блокировка деградации + откат на `development` с
release merge-lease (`_handle_coverage_gate`); AC-3 чистая функция `compute_coverage_verdict`
покрыта по всем режимам/границам/epsilon (TC-01…04); AC-4 ratchet up-only + bootstrap + per-repo
изоляция + атомарный compare-and-set `UPDATE … WHERE coverage <= ?` (`db.ratchet_coverage_baseline`);
AC-5 kill-switch/scope + `applies(repo)` ПЕРВЫМ (дорогой прогон только при `applies==True`) —
регресс зелёный, enduro не затронут; AC-6 fail-open дефолт / fail-closed по флагу; AC-7 never-raise
+ leaf (не импортирует `stage_engine`) + AST-проверка отсутствия деплой/force-push токенов; AC-8
контракты `STAGE_TRANSITIONS`/`check_*`/вердикт-ключи байт-в-байт, таблица `coverage_baseline`
аддитивна; AC-9 вердикт только из frontmatter (`parse_coverage_status` через
`frontmatter.parse_frontmatter`) + `GET /queue` блок `coverage` + Telegram с кликабельным номером.

**2. Соответствие ADR (ADR-001 D1…D8 / adr-0029) — PASS** (с P2-оговоркой по тексту D7).
Порядок под-гейтов `security → merge → coverage → image-freshness` реализован ровно как в D1
(врезка `_handle_coverage_gate` между merge-handling и ORCH-058 freshness в `advance_stage`);
coverage ПОСЛЕ merge-gate (догнанный HEAD) и `merge_gate.release_merge_lease` при FAIL —
соответствует D1/TR-2 (зеркало image-freshness rollback, в отличие от security — тот до захвата
lease). Ratchet в choke-point `_handle_merge_verify` (ребро `deploy→done`, D5), БД-таблица
`coverage_baseline` (D4), машинный вердикт/парсинг (D7), override `POST /coverage/baseline` (D8).
Глобальные ADR (INV-4 merge только через Gitea API; не трогать `main`/прод) не нарушены — leaf
только мерит/читает/пишет/решает.

**3. Качество кода — PASS.**
Docstrings на всех публичных функциях; never-raise контракт выдержан последовательно (все
внешние границы обёрнуты, исключение не всплывает в `advance_stage`); единый frontmatter-контракт
переиспользован (нет дублирования парс-логики); тесты содержательные (режимы/границы/epsilon,
ratchet up-only + bootstrap + per-repo изоляция, fail-open/closed, never-raise, write/read-back
отчёта, self-hosting AST-инвариант, интеграция в `advance_stage` с откатом+release lease).
Фикс `sys.executable` вместо bare `python` (коммит `8cd7c20`) корректен — pytest-cov живёт в
интерпретаторе орка. Нет утечек/security-дыр; измерение offline. Замечание (не finding):
синхронный `pytest --cov` в hot-path `advance_stage` (тайм-аут `coverage_run_timeout_s=900`)
наследует established-паттерн merge-gate re-test/security-gate — нового класса риска не вводит.

**4. Документация — см. раздел «Документация» выше (P0-условие выполнено; обзорные доки N/A).**

**Трассировка маркеров (TRACEABILITY).** Правки рядом с маркерами `ORCH-022`/`ORCH-043`/`ORCH-058`
в `advance_stage` — аддитивная врезка между merge-gate и image-freshness; инварианты соседних
под-гейтов не сломаны (release-lease зеркалит image-freshness rollback, merge через Gitea API
не тронут). Врезка в `_handle_merge_verify` (ORCH-071/073) — never-raise best-effort ratchet,
SHA-in-main choke-point не изменён. Чужие артефакты не повреждены (восстановлена запись ORCH-095).
