94 lines
6.9 KiB
Markdown
94 lines
6.9 KiB
Markdown
---
|
||
type: review
|
||
work_item_id: ORCH-076
|
||
verdict: APPROVED
|
||
version: 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).
|
||
|
||
Документация полная и согласованная — претензий нет.
|