refactor(frontmatter): unified frontmatter contract + handoff spec (ORCH-52c)

src/frontmatter.py grows from a single-key reader into the full machine
contract: reader (read_frontmatter_value, unchanged), one parse primitive
(parse_frontmatter), writer (render/write_frontmatter), schema validator
(validate_schema/REQUIRED_FIELDS, warning-only by default) and a shared
strip_frontmatter helper. The five verdict gates (check_reviewer_verdict,
_parse_tests_verdict, _parse_deploy_status, _parse_staging_status,
parse_security_status) now read through the single parse_frontmatter point
instead of duplicated ad-hoc YAML logic; review_parse._strip_frontmatter and
security_gate.extract_security_findings reuse the shared helper.

Strictly backward compatible + never-raise: STAGE_TRANSITIONS, the QG_CHECKS
composition, verdict semantics (incl. ORCH-047 three-field tester + negative
token priority), reason-strings and worktree->origin/main fallback are 1:1.
The schema validator never influences a gate verdict by default; hard-fail is
reserved behind the frontmatter_validation_strict kill-switch (default False).

New formal handoff spec docs/_standards/HANDOFF_PROTOCOL.md ("stage -> required
output" + required frontmatter schema), aligned 1:1 with PIPELINE_DOCS.md.

Tests: test_frontmatter.py (TC-01..07), test_qg_verdicts.py (TC-08..15),
test_security_gate.py (TC-12), test_stages_invariants.py (TC-16). Full
tests/ green (1212).

Refs: ORCH-076

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

CHANGELOG.md

@@ -3,6 +3,12 @@
 Формат: [Keep a Changelog](https://keepachangelog.com/). Записи — на смысловой PR/задачу.
 
 ## [Unreleased]
+- **Единый frontmatter-контракт (reader + writer + валидатор) + спека handoff** (ORCH-076 / ORCH-52c, `refactor`/`docs`): слой 2 эпика ORCH-52 — `src/frontmatter.py` из single-key reader превращён в **полный машинный контракт**, а **разрознённое чтение вердиктов** пяти гейтов сведено к **одной точке парсинга**. Строго обратно совместимо, never-raise; `STAGE_TRANSITIONS` / состав `QG_CHECKS` / семантика вердиктов / fallback `worktree→origin/main` / трёх-полевой контракт tester (ORCH-047) — **1:1, без изменений**.
+  - **`src/frontmatter.py` (контракт):** сохранён reader `read_frontmatter_value` (контракт неизменен — внешние вызыватели `usage.py` / `notifications.build_status_comment` не затронуты, INV-3); добавлены единый парс-примитив `parse_frontmatter(content) -> FrontmatterParse` (`data/has_block/malformed/yaml_error` — единственная точка YAML-логики) + ярлыки `parse_frontmatter_dict` / `read_frontmatter`; writer `render_frontmatter`/`write_frontmatter` (формат байт-совместим с `split("---",2)`+`yaml.safe_load`, round-trip render→parse); валидатор схемы `validate_schema`/`SchemaValidation`/`REQUIRED_FIELDS` (`work_item/stage/author_agent/status/created_at/model_used`); общий `strip_frontmatter`. Весь модуль — **never-raise** (NFR-2): любая ошибка I/O/YAML/сериализации → лог + безопасное значение (`{}`/`False`/исходный текст).
+  - **Унифицирован МЕХАНИЗМ, а не семантика (D2):** пять вердикт-парсеров — `check_reviewer_verdict` (`verdict:`), `_parse_tests_verdict` (`result:`/`verdict:`/`status:`, ORCH-047), `_parse_deploy_status` (`deploy_status:`), `_parse_staging_status` (`staging_status:`) в `src/qg/checks.py`; `parse_security_status` (`security_status:`) в `src/security_gate.py` — заменили дублированный блок `startswith/split/safe_load/isinstance` на `parse_frontmatter(content)`; token-логика, upper-casing, приоритет негативного токена, reason-строки — сохранены 1:1. Также сняты дубли в `security_gate.extract_security_findings` и `review_parse._strip_frontmatter` (делегируют `strip_frontmatter`).
+  - **Валидатор не hard-fail по умолчанию (D3, критично для self-hosting):** `maybe_warn_schema` при дефолте только логирует `logger.warning("frontmatter schema incomplete: …")` и **никогда не влияет на boolean-вердикт** гейта (инертен). Жёсткий режим — ТОЛЬКО под kill-switch `frontmatter_validation_strict` (env `ORCH_FRONTMATTER_VALIDATION_STRICT`, дефолт `False`; остаётся `False` в проде/`.env.staging`, иначе ORCH-52c self-block'нулась бы — её доки без полной схемы). Схема **аддитивна**: старый док-вердикт без новых полей читается ровно как раньше (FR-5/AC-4).
+  - **Спека handoff:** новый `docs/_standards/HANDOFF_PROTOCOL.md` — формальный контракт «стадия → обязательные документы + frontmatter-ключи на выходе» + обязательная схема (`REQUIRED_FIELDS`), согласован 1:1 с `PIPELINE_DOCS.md` §2–§3; `PIPELINE_DOCS.md` §5–§6 обновлён (слой 2 реализован, ссылка на спеку и `src/frontmatter.py`).
+  - **Без изменений API / схемы БД** (INV-5). Тесты: `tests/test_frontmatter.py` (TC-01…TC-07: writer/round-trip/валидатор/strict/never-raise/reader), `tests/test_qg_verdicts.py` (TC-08…TC-15: семантика пяти гейтов 1:1, обратная совместимость, fallback origin/main), `tests/test_security_gate.py` (TC-12), `tests/test_stages_invariants.py` (TC-16: `QG_CHECKS`/`STAGE_TRANSITIONS` неизменны). Полный регресс `tests/` зелёный (1212). Конфиг: `src/config.py` (`frontmatter_validation_strict`). Документация: `CLAUDE.md`, `docs/architecture/README.md`. ADR: `docs/work-items/ORCH-076/06-adr/ADR-001-frontmatter-contract.md`, сквозной `docs/architecture/adr/adr-0020-frontmatter-contract.md`.
 - **Стандарт документов конвейера: `docs/_standards/PIPELINE_DOCS.md` + `docs/_templates/` + ADR-naming** (ORCH-075 / ORCH-52b, `docs`): зафиксирован golden source структуры номерных документов work item (`00-business-request.md` … `17-security-report.md`). **Docs-only**, нулевой рантайм-риск: `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / `src/stage_engine.py` / схема БД — **не трогаются** (изменения только под `docs/**` + `CLAUDE.md`).
   - **Манифест** `docs/_standards/PIPELINE_DOCS.md` — карта «стадия → агент → документ → категория (`required`/`when-applicable`/`optional`) → гейт/механизм → frontmatter machine-key», сверенная с `src/stages.py` (`STAGE_TRANSITIONS`) и `src/qg/checks.py` (`_parse_*`). Манифест **документирует** поведение гейтов, но НЕ источник истины (источник — код, ADR-001 §D2); честно различает machine-verdict доки (`12`→`verdict:`, `13`→`result:`, `14`→`deploy_status:`, `15`→`staging_status:`, `17`→`security_status:`) и информационные (`00/08/10/16` — гейтом не парсятся). Под-гейты ребра `deploy-staging→deploy` (security/merge/image-freshness) помечены как врезки в `advance_stage`, а не строки `STAGE_TRANSITIONS`.
   - **Шаблоны** `docs/_templates/*` (15 копируемых скелетов) — для каждого `required`/`when-applicable` дока; машинные доки несут точный frontmatter-ключ из ground-truth (`_parse_*`), чтобы скопированный скелет проходил гейт без угадывания. Служебные каталоги `docs/_standards/` / `docs/_templates/` лежат ВНЕ `docs/work-items/<plane-id>/` → невидимы гейтам наличия файлов (`check_architecture_done`/`check_analysis_complete`).