orchestrator/docs/work-items/ORCH-027/12-review.md

verdict, work_item, stage, author_agent, status, created_at, model_used, type, work_item_id, version

verdict	work_item	stage	author_agent	status	created_at	model_used	type	work_item_id	version
REQUEST_CHANGES	ORCH-027	review	reviewer	changes-requested	2026-06-10	claude-opus-4-8	review	ORCH-027	1

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

Summary

Сильная, дисциплинированная реализация детерминированного coverage-гейта по образцу security/merge/image-freshness под-гейтов. Соответствие ТЗ/ADR — полное; код качественный, тесты содержательны (29/29 в test_coverage_gate.py зелёные, регресс реестров 89/89 зелёный); документация обновлена исчерпывающе. Блокирует приёмку ровно один дефект: PR-коммит испортил соседнюю запись ORCH-095 в CHANGELOG.md — тело абзаца продублировано дословно (артефакт чужого work item повреждён). Это must-fix (дублирование в golden-source доке + правка артефакта другой задачи, нарушение CLAUDE.md §3). Фикс тривиален.

Проверено: 4 оси (ТЗ / ADR / качество кода / документация) + трассировка маркеров.

Findings

P0 — Blocker

• (нет)

P1 — Must fix

• CHANGELOG.md: запись ORCH-095 повреждена — тело абзаца продублировано. В строке 16 bullet ORCH-095 заканчивается …откат = git revert). и затем повторяет весь свой текст заново (карточка задачи (src/notifications.py::render_task_tracker)… → карточка застывает… откат = git revert).). Это (а) дублирование в golden-source доке (severity P1 по рубрике reviewer) и (б) правка артефакта другой задачи ORCH-095 (нарушение CLAUDE.md «Правила для агентов §3 — никогда не править артефакты других этапов»; ORCH-027 при вставке своего блока затёр/задублировал чужую запись). Действие: удалить дублирующую половину bullet ORCH-095 — оставить ровно один экземпляр тела, заканчивающийся на первом откат = git revert).. Запись ORCH-027 трогать не нужно — она корректна.

P2 — Should fix

• (нет)

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

Статус: обновлена исчерпывающе (golden source синхронизирован в том же PR, AC-10 PASS — с оговоркой P1 выше по чистоте записи ORCH-095):

• docs/architecture/README.md — реестр QG_CHECKS дополнен check_coverage_gate (ORCH-027); добавлен раздел «Coverage-гейт: защита от деградации покрытия» (точка/порядок, измерение, чистая функция, baseline+ratchet, условность, артефакт/наблюдаемость). ✅
• docs/_standards/PIPELINE_DOCS.md — диапазон доков …18-coverage-report.md; строка карты стадия→агент→документ→гейт→machine-key и строка таблицы вердикт-парсеров. ✅
• docs/_templates/18-coverage-report.md — скелет с frontmatter (coverage_status: + measured/baseline/floor/policy/epsilon/delta) зарегистрирован. ✅
• 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 (P1). ⚠️
• .env.example / src/config.py — флаги ORCH_COVERAGE_* задокументированы. ✅
• Маркеры ORCH-027 проставлены в коде/доках (AC-10). ✅

src/ изменён → документация обновлена в том же PR: да (P0-условие выполнено). Остаточный дефект — чистота соседней записи (P1), не отсутствие документации.

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

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, TC-13); AC-3 чистая функция compute_coverage_verdict покрыта по всем режимам/границам/epsilon (TC-01…04, TC-10); AC-4 ratchet up-only + bootstrap + per-repo изоляция + атомарный compare-and-set (TC-05/06, db.ratchet_coverage_baseline); AC-5 kill-switch/scope/applies ПЕРВЫМ (TC-07/08); AC-6 fail-open дефолт / fail-closed по флагу (TC-09); AC-7 never-raise + leaf + AST-проверка отсутствия деплой/force-push токенов (TC-10/12); AC-8 контракты байт-в-байт, таблица аддитивна (TC-15); AC-9 вердикт только из frontmatter + GET /queue блок + Telegram (TC-11/15).

2. Соответствие ADR (ADR-001 D1…D8 / adr-0029) — PASS. Порядок под-гейтов security → merge → coverage → image-freshness реализован ровно как в D1 (stage_engine.py строки 315→323→333→344); coverage ПОСЛЕ merge-gate (догнанный HEAD) и release merge-lease при FAIL — соответствует D1/TR-2. Ratchet в choke-point _handle_merge_verify (D5), БД-таблица coverage_baseline (D4), машинный вердикт/парсинг через frontmatter.parse_frontmatter (D7), override POST /coverage/baseline (D8). Глобальные ADR (INV merge через Gitea API, не трогать main/прод) не нарушены — leaf только мерит/читает/пишет/решает.

3. Качество кода — PASS. Docstrings на всех публичных функциях; never-raise контракт выдержан последовательно; единый frontmatter-контракт переиспользован (нет дублирования парс-логики); тесты содержательные, включают реальный прогон pytest-cov на фикстур-репо (TC-14) и AST-инвариант self-hosting-безопасности (TC-12). Нет утечек/security-дыр; измерение offline. Мелочь (не finding): чтение coverage-JSON независимо от exit-code корректно прикрыто upstream-гейтами (check_ci_green/merge re-test) и явно объяснено в коде.

4. Документация — см. раздел «Документация» выше (P0-условие выполнено; P1 по чистоте ORCH-095).

Трассировка маркеров (TRACEABILITY): правки рядом с маркерами ORCH-022/ORCH-043/ORCH-058 в advance_stage — аддитивная врезка между merge-gate и image-freshness, инварианты соседних под-гейтов не сломаны (release-lease зеркалит image-freshness rollback). Единственное нарушение трассировки/чужого артефакта — повреждённая запись ORCH-095 в CHANGELOG (P1 выше).