ORCH-076 — ORCH-52c: единый frontmatter-контракт (reader/writer/валидатор) + спека handoff #92

admin · 2026-06-09T14:04:27+03:00

admin commented

2026-06-09 14:04:27 +03:00

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

Слой 2 эпика ORCH-52. src/frontmatter.py превращён из single-key reader в полный машинный контракт; разрознённое чтение вердиктов пяти гейтов сведено к одной точке парсинга. Строго обратно совместимо, never-raise, нулевая поведенческая регрессия.

Что сделано

src/frontmatter.py: сохранён reader read_frontmatter_value (контракт неизменен, INV-3); добавлены единый примитив parse_frontmatter (data/has_block/malformed/yaml_error), writer render/write_frontmatter (формат совместим с существующими парсерами, round-trip), валидатор validate_schema/REQUIRED_FIELDS, общий strip_frontmatter. Весь модуль never-raise.
Унифицирован механизм, не семантика (D2): check_reviewer_verdict, _parse_tests_verdict, _parse_deploy_status, _parse_staging_status (qg/checks.py), parse_security_status (security_gate.py) делегируют parse_frontmatter; token-логика, ORCH-047 (3 поля + приоритет негатива), reason-строки, fallback worktree→origin/main — 1:1. Сняты дубли в extract_security_findings / review_parse._strip_frontmatter.
Валидатор не hard-fail по умолчанию (D3): maybe_warn_schema инертен (warning-only); hard-fail только под kill-switch frontmatter_validation_strict (env ORCH_FRONTMATTER_VALIDATION_STRICT, дефолт False). Схема аддитивна — старые доки читаются как раньше (FR-5/AC-4).
Спека handoff: docs/_standards/HANDOFF_PROTOCOL.md (стадия → обязательный выход + frontmatter-схема), согласована 1:1 с PIPELINE_DOCS.md.

Инварианты (AC-6)

STAGE_TRANSITIONS, состав QG_CHECKS, семантика вердиктов, API, схема БД — без изменений.

Тесты

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). Полный регресс tests/ зелёный — 1212 passed.

ADR: docs/work-items/ORCH-076/06-adr/ADR-001-frontmatter-contract.md, сквозной docs/architecture/adr/adr-0020-frontmatter-contract.md.

Refs: ORCH-076

🤖 Generated with Claude Code

## ORCH-076 — ORCH-52c: единый frontmatter-контракт + спека handoff Слой 2 эпика ORCH-52. `src/frontmatter.py` превращён из single-key reader в полный машинный контракт; разрознённое чтение вердиктов пяти гейтов сведено к одной точке парсинга. **Строго обратно совместимо, never-raise, нулевая поведенческая регрессия.** ### Что сделано - **`src/frontmatter.py`**: сохранён reader `read_frontmatter_value` (контракт неизменен, INV-3); добавлены единый примитив `parse_frontmatter` (`data/has_block/malformed/yaml_error`), writer `render/write_frontmatter` (формат совместим с существующими парсерами, round-trip), валидатор `validate_schema`/`REQUIRED_FIELDS`, общий `strip_frontmatter`. Весь модуль never-raise. - **Унифицирован механизм, не семантика (D2)**: `check_reviewer_verdict`, `_parse_tests_verdict`, `_parse_deploy_status`, `_parse_staging_status` (`qg/checks.py`), `parse_security_status` (`security_gate.py`) делегируют `parse_frontmatter`; token-логика, ORCH-047 (3 поля + приоритет негатива), reason-строки, fallback `worktree→origin/main` — 1:1. Сняты дубли в `extract_security_findings` / `review_parse._strip_frontmatter`. - **Валидатор не hard-fail по умолчанию (D3)**: `maybe_warn_schema` инертен (warning-only); hard-fail только под kill-switch `frontmatter_validation_strict` (env `ORCH_FRONTMATTER_VALIDATION_STRICT`, дефолт `False`). Схема аддитивна — старые доки читаются как раньше (FR-5/AC-4). - **Спека handoff**: `docs/_standards/HANDOFF_PROTOCOL.md` (стадия → обязательный выход + frontmatter-схема), согласована 1:1 с `PIPELINE_DOCS.md`. ### Инварианты (AC-6) `STAGE_TRANSITIONS`, состав `QG_CHECKS`, семантика вердиктов, API, схема БД — **без изменений**. ### Тесты `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). Полный регресс `tests/` зелёный — **1212 passed**. ADR: `docs/work-items/ORCH-076/06-adr/ADR-001-frontmatter-contract.md`, сквозной `docs/architecture/adr/adr-0020-frontmatter-contract.md`. Refs: ORCH-076 🤖 Generated with [Claude Code](https://claude.com/claude-code)

admin added 6 commits 2026-06-09 14:14:31 +03:00

docs: init ORCH-076 business request 561f58abe0

analyst(ET): auto-commit from analyst run_id=453 98c50a094b

architect(ET): auto-commit from architect run_id=454 2030d1627a

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

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>

reviewer(ET): auto-commit from reviewer run_id=456 d846910ca6

tester(ET): auto-commit from tester run_id=457

CI / test (push) Successful in 36s

Details

CI / test (pull_request) Successful in 31s

Details

cb9bfcff12

admin force-pushed feature/ORCH-076-orch-52c-handoff-frontmatter-w from eba811c993 to cb9bfcff12

2026-06-09 14:14:31 +03:00

Compare

admin merged commit 3602eee69f into main

2026-06-09 14:18:43 +03:00

admin referenced this issue from a commit

2026-06-09 14:18:44 +03:00

Merge pull request 'ORCH-076 — ORCH-52c: единый frontmatter-контракт (reader/writer/валидатор) + спека handoff' (#92) from feature/ORCH-076-orch-52c-handoff-frontmatter-w into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: admin/orchestrator#92