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

type, work_item_id, verdict, version

type	work_item_id	verdict	version
review	ORCH-076	APPROVED	1

Review ORCH-076 — ORCH-52c: единый frontmatter-контракт + спека handoff

Summary

Изменение реализует слой 2 эпика ORCH-52: src/frontmatter.py превращён из single-key reader'а в полный машинный контракт (reader + writer + валидатор схемы + единый парс-примитив), а дублированное чтение YAML-frontmatter в пяти вердикт-парсерах сведено к одной точке (parse_frontmatter). Дополнительно создана формальная спека handoff (docs/_standards/HANDOFF_PROTOCOL.md).

Реализация полностью соответствует ТЗ и ADR-001/adr-0020: унифицирован только МЕХАНИЗМ парсинга (D2), семантика вердиктов, token-логика, приоритет негативного токена, fallback worktree→origin/main и трёх-полевой контракт tester (ORCH-047) сохранены 1:1. Валидатор warning-only по умолчанию, hard-fail только под kill-switch frontmatter_validation_strict (дефолт False) — критично для self-hosting (задача не self-block'ится). Весь модуль never-raise. STAGE_TRANSITIONS и состав QG_CHECKS не тронуты (подтверждено TC-16).

Проверка по осям:

• Соответствие ТЗ: FR-1…FR-6 реализованы (writer, валидатор, полночтение, единый контракт вердиктов, BC старых доков, спека handoff). API/БД не тронуты (TRZ §4–§5). ✓
• Соответствие AC: AC-1…AC-7 выполнены (см. ниже). ✓
• Соответствие ADR: D1–D5 реализованы как спроектировано (функции в leaf-модуле, unify-механизм-не-семантику, warning-only validator, спека handoff, без API/БД). ✓
• Качество кода: docstrings на всех публичных функциях; never-raise контракт выдержан (broad-except + лог + безопасный возврат); leaf-модуль без проектных импортов (cycle-free).
• Тесты: содержательные, покрывают writer/round-trip/валидатор/strict/never-raise/reader (test_frontmatter.py), семантику пяти гейтов + BC + origin/main fallback (test_qg_verdicts.py), security-гейт (test_security_gate.py), инварианты реестра (test_stages_invariants.py). Полный регресс 1212 passed.

Проверка AC:

• AC-1 (reader+writer+валидатор, unit-tested): ✓ read_frontmatter_value (BC), render/write_frontmatter, validate_schema с 6 полями REQUIRED_FIELDS; TC-01…TC-07.
• AC-2 (спека handoff в docs/_standards/, согласована): ✓ покрывает все стадии created→done, набор документов/ключей/гейтов 1:1 с PIPELINE_DOCS.md §2–§3; PIPELINE_DOCS.md обновлён ссылкой + отметкой реализации (§5–§6).
• AC-3 (единый контракт вердиктов): ✓ все 5 (check_reviewer_verdict, _parse_tests_verdict, _parse_deploy_status, _parse_staging_status, parse_security_status) делегируют parse_frontmatter; ad-hoc блоки удалены.
• AC-4 (BC старых доков + регресс зелёный): ✓ TC-13/TC-14 для старых доков без схемы; 1212 tests green.
• AC-5 (never-raise + warning-only + kill-switch): ✓ TC-05 (битый ввод), maybe_warn_schema инертен при дефолте, frontmatter_validation_strict в config.py.
• AC-6 (STAGE_TRANSITIONS/QG_CHECKS неизменны, семантика 1:1): ✓ TC-16; вердикт-логика не тронута.
• AC-7 (документация): ✓ см. раздел «Документация».

Findings

P0 — Blocker

• Нет.

P1 — Must fix

• Нет.

P2 — Should fix

• Нет.

P3 — Nice-to-have

• _parse_tests_verdict (src/qg/checks.py): для редкого случая «валидный YAML, но не mapping» во frontmatter старая ветка возвращала reason "Malformed YAML frontmatter in test report (not a mapping)", новая реализация маршрутизирует этот ввод в путь пустых данных → reason "No machine-readable verdict/status/result in test report frontmatter". Boolean-вердикт идентичен (False в обоих случаях) → семантика и STAGE_TRANSITIONS не затронуты (AC-6 соблюдён). Расхождение только в reason-строке (лог/коммент). ADR D2 заявляет «reason-строки 1:1» — здесь незначительное отклонение в крайне редком кейсе. Можно при желании добавить явную ветку для паритета, но это не обязательно.
• parse_security_status (src/security_gate.py) не вызывает maybe_warn_schema, тогда как 4 из 5 вердикт-парсеров его вызывают. Поскольку warning инертен (не влияет на вердикт), это чисто косметическая несогласованность наблюдаемости. Для единообразия можно добавить вызов.

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

Обновлено в том же PR (golden source синхронен с кодом, правило CLAUDE.md №2/№6):

• CLAUDE.md — блок про единый frontmatter-контракт в «Конвенциях».
• docs/architecture/README.md — «Канон гейтов» (единый контракт), компонент frontmatter, ссылки на спеку handoff и adr-0020.
• docs/_standards/HANDOFF_PROTOCOL.md — создан (спека handoff, все стадии, обязательная схема REQUIRED_FIELDS).
• docs/_standards/PIPELINE_DOCS.md — обновлён (слой 2 реализован, §5–§6 + ссылки).
• CHANGELOG.md — детальная запись [Unreleased].
• ADR: per-work-item docs/work-items/ORCH-076/06-adr/ADR-001-frontmatter-contract.md + сквозной docs/architecture/adr/adr-0020-frontmatter-contract.md; индекс docs/architecture/adr/README.md обновлён (adr-0018/0019/0020, max=0020).

Документация полная и согласованная — претензий нет.