adr-0019: Стандарт документов пайплайна (docs/_standards + docs/_templates + ADR-naming)

Статус: proposed · Дата: 2026-06-09 · Источник: ORCH-075 (ORCH-52b, слой 1 эпика ORCH-52) Детально: docs/work-items/ORCH-075/06-adr/ADR-001-pipeline-docs-standard.md.

Контекст

Агенты всех ролей пишут номерные доки work item (00…17) «по памяти»; каталогов docs/_standards/ и docs/_templates/ нет. Следствия: разнобой структуры между задачами; риск рассинхрона критичных frontmatter-ключей машинных доков (verdict: / result: / deploy_status: / staging_status: / security_status:), которые читает гейт; отсутствует целостная карта «стадия → агент → документ → гейт». Эпик ORCH-52 слоист: слой 1 (52b) фиксирует договорённость, машинная проверка/валидатор — отдельный слой 52c.

Решение

Документационный стандарт, docs-only, выведенный из фактического кода и эталонных доков:

docs/_standards/PIPELINE_DOCS.md — манифест-карта «стадия → документ → владелец-агент → категория (required/when-applicable/optional) → гейт/механизм → frontmatter machine-key». Манифест документирует поведение гейтов (источник истины остаётся src/), честно различает machine-verdict доки (12,13,14,15,17) и информационные (00,08,10,16), и помечает под-гейты ребра deploy-staging→deploy (security/merge/image-freshness) как врезки в advance_stage, а не строки STAGE_TRANSITIONS.
docs/_templates/* — копируемые скелеты для каждого required/when-applicable дока; секции выведены из эталонов (ORCH-088/073/089/071), новые не изобретаются; машинные доки несут точный frontmatter-ключ из ground-truth.
ADR-naming канонизирован: docs/work-items/<plane-id>/06-adr/ADR-NNN-<kebab-slug>.md (NNN с 001); кросс-каттинговые решения дублируются в этот глобальный реестр adr-NNNN-<slug>.md.

Подключение — ссылки из CLAUDE.md и docs/architecture/README.md + запись в CHANGELOG.md.

Альтернативы

Сразу валидатор на гейте — отвергнуто (ORCH-52c; нарушил бы docs-only/NFR-1, групповой риск).
Манифест как источник истины гейтов — отвергнуто (дубль-истина «манифест ≠ код»).
Шаблоны в docs/work-items/_template/ — отвергнуто (риск для сканеров/гейтов наличия файлов).
Ретро-фит истории доков — отвергнуто (вне scope, отдельный риск).

Последствия

+ Единый golden source структуры доков; меньше ложных падений гейтов из-за неверного frontmatter-ключа; ADR-naming записан; база для ORCH-52c.
+ Нулевой рантайм-риск: только docs/** + CLAUDE.md + CHANGELOG.md; STAGE_TRANSITIONS / QG_CHECKS / check_* / src/stage_engine.py / схема БД — без изменений; полностью обратимо.
− Манифест — снимок поведения гейтов, дрейфует до ORCH-52c (митигейшн: источник истины — код, reviewer-правило, привязка к именам check_*); стандарт описательный, не принуждающий.

Связи

Источник: ORCH-075 (docs/work-items/ORCH-075/06-adr/ADR-001-pipeline-docs-standard.md).
Документирует (не меняет): adr-0003/0006/0008/0012/0013/0014/0016 (гейты и под-гейты ребра), STAGE_TRANSITIONS (src/stages.py), QG_CHECKS (src/qg/checks.py).
Downstream: ORCH-52c (frontmatter-валидатор / writer-контракт), ORCH-52d (правка промптов).

4.6 KiB Raw Permalink Blame History Unescape Escape