01 — BRD (бизнес-требования): ORCH-076 — ORCH-52c: протокол handoff + frontmatter-контракт (writer/валидатор/схема)

Work Item: ORCH-076 · Repo: orchestrator · Стадия: analysis

1. Бизнес-контекст и проблема

Это слой 2 эпика ORCH-52 (стандартизация документного конвейера). Слой 1 (ORCH-52b / ORCH-075) уже в main: создан описательный стандарт docs/_standards/PIPELINE_DOCS.md

копируемые скелеты docs/_templates/*. Стандарт честно фиксирует карту «стадия → агент → документ → гейт → frontmatter machine-key», но прямо помечен как слой описательный: «Машинная проверка соответствия шаблонам/frontmatter — отдельная задача ORCH-52c».

Установленные факты (проверено в репо на ветке задачи):

src/frontmatter.py = ТОЛЬКО reader. Единственная функция read_frontmatter_value(path, key) -> str | None (single-key, ~2.6 KB). В docstring модуля прямой коммент: «merging into a single parser is a follow-up task» — это и есть ORCH-52c. Контракт reader — never raises (любая ошибка → None + logger.debug).
Протокол вердиктов размазан по отдельным парсерам с дублированной ~10-строчной YAML-frontmatter-логикой:
- src/qg/checks.py::check_reviewer_verdict — читает verdict: из 12-review.md;
- src/qg/checks.py::_parse_tests_verdict — читает result:/verdict:/status: из 13-test-report.md (три равноранговых поля, ORCH-047);
- src/qg/checks.py::_parse_deploy_status — читает deploy_status: из 14-deploy-log.md;
- src/qg/checks.py::_parse_staging_status — читает staging_status: из 15-staging-log.md;
- src/security_gate.py::parse_security_status — читает security_status: из 17-security-report.md;
- src/post_deploy.py — пишет/читает post_deploy_status: в 16-post-deploy-log.md;
- src/review_parse.py — defensive-извлечение прозы (_strip_frontmatter). Каждый парсер заново реализует content.startswith("---") → split("---", 2) → yaml.safe_load. Единого контракта нет → риск рассинхрона (разная обработка ошибок, разный набор токенов, разный регистр).
Нет формальной спеки handoff: нигде не зафиксировано «что КАЖДАЯ стадия ОБЯЗАНА оставить на выходе» (полный список артефактов + обязательные frontmatter-ключи) как единый контракт передачи между стадиями.

Боль/риск: без единого контракта чтения вердиктов и без обязательной схемы frontmatter каждая правка одного парсера может разойтись с остальными; новый агентский документ легко написать с неверным ключом/регистром (гейт упадёт ложно), а отсутствие машинной проверки схемы оставляет соблюдение стандарта на ручную дисциплину reviewer'а.

⚠️ Self-hosting. Задача меняет КОД, читающий вердикты НА ГЕЙТАХ (review/staging/security/ tester/deploy) в инструменте, который сейчас обслуживает прод (enduro-trails) из общего инстанса. Любой регресс чтения вердикта = остановка конвейера всех проектов. Поэтому рефакторинг обязан быть строго обратно совместимым и fail-safe.

2. Объём (scope)

В объёме

Спека handoff в docs/_standards/ (рядом с PIPELINE_DOCS.md): формальный контракт «стадия → обязательный выход» (какие документы + какие frontmatter-ключи обязательны на выходе каждой стадии), согласованный с манифестом ORCH-52b.
Расширение src/frontmatter.py: к существующему reader добавить writer (запись YAML-frontmatter) и валидатор обязательной схемы. Обязательная схема: work_item, stage, author_agent, status, created_at, model_used.
Единый контракт вердиктов в одном месте (док + единый frontmatter-API): гейты (reviewer→verdict:, tester→result:, deployer→deploy_status:, staging→staging_status:, security→security_status:) читают СТАНДАРТНЫЕ поля через единый frontmatter-API, а не через разрознённые ad-hoc парсеры.
Обновление документации (CLAUDE.md, architecture/README, ADR — глобальный и per-work-item, CHANGELOG).

Вне объёма

Правка промптов агентов (.openclaw/agents/*.md), чтобы те эмитили новую полную схему — это ORCH-52d (слой 3).
Ретро-фит старых документов (дописывание новой схемы в уже существующие work-items).
Изменение STAGE_TRANSITIONS и состава QG_CHECKS (какие гейты существуют).
Изменение семантики вердиктов (какое значение → какой переход) — только КАК они читаются.
Включение hard-fail валидации схемы по умолчанию (дефолт — warning; hard-fail только под явно включённым kill-switch).

3. Заинтересованные стороны

Заказчик / Owner — Слава (homenet542): подтверждает BRD (ручной гейт остаётся ручным).
Самообслуживаемый инструмент (self-hosting) — оркестратор правит сам себя; задача — первый боевой тест autoDeploy (см. примечание ниже).
Затрагиваемые роли конвейера — reviewer / tester / deployer / security-гейт (их вердикты теперь читаются через единый API); architect/analyst (новая обязательная схема для будущих документов, фактическое внедрение — ORCH-52d).
Другие проекты (enduro-trails) — НЕ должны почувствовать изменений (нулевая регрессия).

4. Бизнес-требования (BR)

BR-1 — src/frontmatter.py предоставляет полный набор операций над YAML-frontmatter: reader (сохранён без изменения контракта), writer (сериализация frontmatter в документ), валидатор (проверка обязательной схемы).
BR-2 — Обязательная схема frontmatter определена и проверяема: поля work_item, stage, author_agent, status, created_at, model_used.
BR-3 — Создана формальная спека handoff в docs/_standards/, согласованная с PIPELINE_DOCS.md: для каждой стадии указано, какие документы и какие frontmatter-ключи она обязана оставить на выходе.
BR-4 — Контракт вердиктов сведён в ОДНО место; все пять гейтов-вердиктов (review/staging/security/tester/deploy) читают стандартные поля через единый frontmatter-API, а не через разрознённые парсеры.
BR-5 — Семантика вердиктов неизменна: то же значение → тот же переход/откат, что и сейчас (включая трёх-полевой контракт tester'а ORCH-047 и токен-логику BLOCKED/FAILED).

5. Нефункциональные требования (NFR)

NFR-1 (обратная совместимость, критично self-hosting) — Существующие документы-вердикты БЕЗ новой полной схемы ПРОДОЛЖАЮТ читаться гейтами (fallback на текущее поведение). Старый 12/13/14/15/17-док без work_item/stage/... парсится по вердикт-ключу как раньше.
NFR-2 (never-raise / fail-safe) — Ошибка writer'а или валидатора НЕ роняет конвейер (тот же контракт, что у reader: любая ошибка → лог + безопасное значение, исключение наружу не выходит).
NFR-3 (валидатор не self-block) — Валидатор обязательной схемы НЕ является hard-fail на гейте по умолчанию (иначе сама ORCH-52c заблокировала бы себя на собственном деплое, т.к. её документы и документы соседей ещё без полной схемы). Дефолт — warning/лог; жёсткость — под kill-switch (флаг).
NFR-4 (нулевая регрессия для enduro) — Поведение для не-self-hosting репозиториев и всех существующих гейтов остаётся 1:1; полный регресс tests/ зелёный.
NFR-5 (обратимость) — Поведенческие изменения (если есть, напр. строгая валидация) закрываются kill-switch с дефолтом, эквивалентным прежнему поведению.

6. Допущения и ограничения

Frontmatter везде в каноне — ведущий YAML-блок между --- … --- (как в qg/checks.py и frontmatter.py).
Источник истины о поведении гейтов остаётся КОД (src/stages.py, src/qg/checks.py, src/stage_engine.py); спека/манифест документируют, а не управляют (правило ORCH-075).
model_used в схеме — это модель, которой документ создан; фактический источник значения для агентских доков — резолв resolve_agent_model (ORCH-41); проставление в реальные документы агентами — ORCH-52d, вне scope.
pyyaml уже зависимость проекта (используется во всех существующих парсерах).
Реализационные решения (одна функция-парсер vs класс, точная сигнатура writer/валидатора, имя модуля контракта вердиктов) — прерогатива архитектора (06-adr), здесь не предрешаются.

7. Критерии успеха

Задача успешна, если: src/frontmatter.py несёт reader+writer+валидатор обязательной схемы; спека handoff создана и согласована с PIPELINE_DOCS.md; все пять гейтов-вердиктов читают через единый frontmatter-API; старые доки-вердикты продолжают проходить гейты (анти-регресс); ошибка writer/валидатора не роняет конвейер, hard-fail валидации под kill-switch (дефолт — warning); STAGE_TRANSITIONS и состав QG_CHECKS не изменены, семантика вердиктов неизменна; документация обновлена; сама ORCH-52c проходит свои гейты (включая первый боевой autoDeploy). Детальные PASS/FAIL — 03-acceptance-criteria.md.

8. Риски

Регресс чтения вердикта на гейте → остановка конвейера всех проектов (главный риск self-hosting). Митигация — строгая обратная совместимость + полный регресс тестов гейтов.
Самоблокировка валидатором на собственном деплое (документы без полной схемы). Митигация — NFR-3 (валидатор не hard-fail по умолчанию).
Расхождение спеки handoff с фактом кода → «лживый» стандарт. Митигация — согласование с PIPELINE_DOCS.md и явная пометка «источник истины — код».
Первый боевой autoDeploy — авто-подтверждение прод-деплоя орка (см. примечание). Детали митигации/наблюдения — задача архитектора (10-tech-risks.md).

Примечание (АВТО-ДЕПЛОЙ). На этой задаче выставлен лейбл autoDeploy (ORCH-089): орк САМ подтверждает прод-деплой после зелёного staging + всех тех-гейтов. BRD-гейт остаётся ручным (Слава подтверждает BRD). Это первый боевой тест autoDeploy.

14 KiB Raw Permalink Blame History Unescape Escape