# 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, выведенный из фактического кода и эталонных доков:**

1. `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`.
2. `docs/_templates/*` — копируемые скелеты для каждого `required`/`when-applicable` дока; секции
   выведены из эталонов (ORCH-088/073/089/071), новые не изобретаются; машинные доки несут точный
   frontmatter-ключ из ground-truth.
3. **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 (правка промптов).
