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

Work Item: **ORCH-075** (ORCH-52b — слой 1 эпика ORCH-52)
Стадия: **architecture**
Сквозная регистрация: **`docs/architecture/adr/adr-0019-pipeline-docs-standard.md`** (решение
кросс-каттинговое — задаёт правила доко-письма для ВСЕХ агентских ролей).

## Статус
Proposed

## Контекст
Агенты конвейера (`analyst → architect → developer → reviewer → tester → deployer` + системные
акторы deploy-finalizer / post-deploy-monitor / security-гейт) пишут номерные документы work item
(`00-business-request.md` … `17-security-report.md`) «с нуля по памяти». Каталогов
`docs/_standards/` и `docs/_templates/` не существует (проверено в репо). Следствия:

- **Разнобой структуры** одного и того же документа от задачи к задаче (набор/порядок секций
  плавает) — затрудняет ревью и онбординг новых ролей.
- **Риск рассинхрона машинных вердиктов.** Доки `12-review.md` / `13-test-report.md` /
  `14-deploy-log.md` / `15-staging-log.md` / `17-security-report.md` несут frontmatter-ключ,
  который читает гейт (`verdict:` / `result:` / `deploy_status:` / `staging_status:` /
  `security_status:`), но единого канонического скелета с этим ключом нет → агент может выдать
  ключ не того имени/регистра и уронить гейт ложно.
- **Нет карты «стадия → агент → документ → гейт».** Какая роль пишет какой документ и где он
  проверяется — нигде не зафиксировано целостно.

Эпик ORCH-52 намеренно разбит на слои: **сначала зафиксировать договорённость** (golden source
структуры доков), и лишь потом, отдельной задачей (52c), навесить машинную проверку
frontmatter/шаблонов на гейте. Слой 1 (эта задача) — **только документация**: манифест,
канонические шаблоны, конвенция ADR-naming. Любой валидатор/правка кода/правка промптов — вне
scope. Ключевое архитектурное ограничение задачи (NFR-1): **ни строки кода/гейтов** — изменения
строго под `docs/**` (+ `CLAUDE.md` / `CHANGELOG.md`).

Ground-truth для манифеста — **фактические** `STAGE_TRANSITIONS` (`src/stages.py`), `QG_CHECKS` /
`check_*` (`src/qg/checks.py`), `src/stage_engine.py` и реальные эталонные доки (ORCH-088/073/089/071),
а не вымысел. Сверка проведена на стадии architecture (см. §Решение D5).

## Решение

### Сводка
Создать **документационный стандарт** из трёх артефактов, выведенный из фактического кода и
эталонных доков, и подключить его ссылками из точек-онбординга. Никаких рантайм-изменений.

- `docs/_standards/PIPELINE_DOCS.md` — манифест-карта «стадия → документ → агент → категория →
  гейт/механизм → frontmatter machine-key» + раздел ADR-naming.
- `docs/_templates/*` — копируемые скелеты для каждого `required` / `when-applicable` дока.
- Ссылки из `CLAUDE.md` и `docs/architecture/README.md`; запись в `CHANGELOG.md`.

### D1 — Местоположение и разделение «стандарт» vs «шаблон»
Два каталога с раздельной ответственностью: `docs/_standards/` — **описательный** golden source
(манифест, конвенции, человекочитаемая карта); `docs/_templates/` — **копируемые** скелеты для
заполнения. Префикс `_` выводит служебные каталоги наверх листинга и визуально отделяет их от
`docs/work-items/` / `docs/architecture/` / `docs/operations/`. Шаблоны — НЕ work item, не имеют
`<plane-id>`, не парсятся гейтами (живут вне `docs/work-items/`), поэтому не влияют на
`check_architecture_done` / `check_analysis_complete` и не попадают под ретро-фит.

### D2 — Манифест как производная от кода, а не параллельный источник истины
`PIPELINE_DOCS.md` **документирует** текущее поведение гейтов, но НЕ становится их источником
истины (источник остаётся `src/`). Это устраняет класс «манифест разошёлся с кодом»: при будущем
изменении гейта (ORCH-52c+) правка кода первична, манифест — следом. Манифест честно различает:
- **machine-verdict доки** (`12,13,14,15,17`) — несут frontmatter-ключ, читаемый гейтом; в
  манифесте помечены ключом и именем `check_*`;
- **информационные доки** (`00,08,10,16`) — гейтом не парсятся; помечены явно как не-гейтящиеся
  (чтобы не возникало ложного ожидания, что их структура что-то блокирует).

Под-гейты ребра `deploy-staging → deploy` (`check_security_gate` → `check_branch_mergeable` →
`check_staging_image_fresh`) в манифесте отмечаются как **врезки в `advance_stage`**, а НЕ строки
`STAGE_TRANSITIONS` — иначе карта соврёт о топологии машины стадий (AC-7).

### D3 — Шаблоны выведены из эталонов, новые секции не изобретаются
Скелеты извлекаются из реальных «golden» задач (ORCH-088/073/089/071) и текущей задачи ORCH-075.
Инвариант (NFR-3): **в шаблоне нет секции, которой никто не пишет в эталонах**, и наоборот — общий
канон секций эталона присутствует. Минимальный обязательный набор секций по каждому документу
зафиксирован в TRZ §FR-2.1 и является контрактом приёмки (AC-2/AC-4). Документы с машинным
вердиктом несут в шаблоне точный frontmatter-ключ из ground-truth таблицы (D5), чтобы скопированный
скелет проходил гейт без догадок.

### D4 — ADR-naming: канонизация сложившейся традиции, не новый формат
Зафиксировать **уже существующий** формат, не вводя нового:
- Путь: `docs/work-items/<plane-id>/06-adr/`.
- Имя: `ADR-NNN-<kebab-slug>.md`; `NNN` с `001`, инкремент при нескольких ADR в одной задаче.
- `slug` — kebab-case (нижний регистр, дефисы), отражает суть решения.
- Кросс-каттинговые решения **дублируются** в глобальном реестре
  `docs/architecture/adr/adr-NNNN-<slug>.md` (4-значная сквозная нумерация) — это уже действующая
  конвенция (подтверждено: реестр идёт до `adr-0018`), лишь записывается.
- Примеры из репо (проверены): `ADR-001-serial-gate`, `ADR-001-auto-label-gates`,
  `ADR-001-merge-verify-gate`.

Сам этот ADR следует конвенции и дублируется как `adr-0019` — стандарт демонстрирует себя.

### D5 — Достоверность: сверка манифеста с `src/` на стадии architecture (NFR-2)
Перед фиксацией манифеста ground-truth сверен с кодом. Подтверждено:

| Документ | Гейт / механизм | Machine-key | Подтверждено в |
|----------|-----------------|-------------|----------------|
| `01–04` | `check_analysis_approved` (exit `analysis→architecture`); helper `check_analysis_complete` (наличие `01/02/03/04`) | — | `stages.py`, `qg/checks.py:check_analysis_complete` |
| `06-adr/` | `check_architecture_done` (наличие каталога `06-adr/` ≥1 файл ИЛИ `07-infra-requirements.md`) | — | `qg/checks.py:check_architecture_done` |
| `12-review.md` | `check_reviewer_verdict` | `verdict:` | `qg/checks.py` |
| `13-test-report.md` | `check_tests_passed` | `result:`/`verdict:`/`status:` (три равноранговых, ORCH-047) | `qg/checks.py:_parse_tests_verdict` |
| `14-deploy-log.md` | `check_deploy_status` | `deploy_status:` | `qg/checks.py:_parse_deploy_status` |
| `15-staging-log.md` | `check_staging_status` (self-hosting; иначе N/A — ORCH-35) | `staging_status:` | `qg/checks.py:_parse_staging_status` |
| `17-security-report.md` | `check_security_gate` (под-гейт ребра `deploy-staging→deploy`) | `security_status:` | `qg/checks.py` |
| `16-post-deploy-log.md` | информационный (пост-`done` наблюдение ORCH-021, не ребро) | `post_deploy_status:` (не гейтится) | `stage_engine.run_post_deploy_monitor` |
| `00/08/10` | не гейтятся (вход / информационные) | — | — |

`STAGE_TRANSITIONS` (проверено): `analysis→architecture→development→review→testing→deploy-staging
→deploy→done`; рёбра несут ровно `check_analysis_approved / check_architecture_done / check_ci_green
/ check_reviewer_verdict / check_tests_passed / check_staging_status / check_deploy_status`.
Под-гейты `security/merge/image-freshness` в `STAGE_TRANSITIONS` **отсутствуют** (врезки в
`advance_stage`) — подтверждает D2.

### D6 — Разграничение ответственности стадий (что пишет архитектор vs разработчик)
Эта стадия (architecture) производит **только** ADR + tech-risks (+ N/A infra/data). Сами артефакты
стандарта (`PIPELINE_DOCS.md`, `docs/_templates/*`) и правки точек-ссылок
(`CLAUDE.md` / `docs/architecture/README.md` / `CHANGELOG.md`) создаёт стадия development по TRZ §2 —
чтобы не было двойного авторства и конфликтов. Архитектор фиксирует **контракт** (что и где должно
появиться, по каким инвариантам), разработчик его **реализует**.

## Альтернативы
- **Один файл-стандарт без каталога шаблонов** — отвергнуто: шаблон должен быть копируемым
  отдельным файлом (UX «скопировал и заполнил», AC-2), а не вырезкой из прозы манифеста.
- **Сразу валидатор frontmatter на гейте** — отвергнуто намеренно (это ORCH-52c): нарушило бы
  NFR-1 (правка кода/гейтов) и подняло бы групповой self-hosting риск без предварительной фиксации
  договорённости. Слой «стандарт» обязан предшествовать слою «проверка».
- **Манифест как источник истины для гейтов** — отвергнуто: породило бы дубль-истину и класс
  «манифест ≠ код». Источник остаётся `src/`; манифест — производная (D2).
- **Положить шаблоны в `docs/work-items/_template/`** — отвергнуто: попадание под `docs/work-items/`
  с `<plane-id>`-семантикой риск-фактор для гейтов наличия файлов и сканеров; служебный каталог
  должен быть вне дерева work item (D1).
- **Ретро-фит существующих доков под новый шаблон** — отвергнуто (вне scope, BRD §2.2): массовая
  правка истории — отдельный риск и шум; стандарт применяется к новым задачам вперёд.
- **Не заводить глобальный `adr-0019`** — отвергнуто: решение кросс-каттинговое (правила
  доко-письма для всех ролей), а FR-3 сам канонизирует дублирование сквозных решений в глобальный
  реестр — стандарт обязан следовать собственному правилу.

## Последствия
- **+** Единая карта «стадия → агент → документ → гейт → machine-key»; копируемые скелеты →
  меньше разнобоя и ложных падений гейтов из-за неверного frontmatter-ключа; ADR-naming перестаёт
  быть устной традицией; готовая база для ORCH-52c (валидатор).
- **+ Нулевой рантайм-риск (NFR-1/NFR-5):** изменения только под `docs/**` + `CLAUDE.md` +
  `CHANGELOG.md`. `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / `src/stage_engine.py` / схема БД —
  **не трогаются**. Удаление новых файлов полностью откатывает изменение без следов в поведении
  системы (обратимость).
- **− Дрейф во времени:** манифест — снимок поведения гейтов; при будущей правке гейта его нужно
  обновлять вручную (до ORCH-52c, где появится проверка). Митигейшн: D2 (источник истины — код) +
  reviewer-правило «обновлена ли документация» + явная привязка манифеста к именам `check_*`.
- **−** Стандарт описательный, не принуждающий: агент может его проигнорировать (форсинг — 52c).
  Осознанно принято как цена слоистого подхода.
- **Откат:** удалить `docs/_standards/PIPELINE_DOCS.md`, `docs/_templates/*`, снять ссылки и запись
  CHANGELOG — система ведёт себя в точности как до ORCH-075.

## Ссылки
- BRD: `docs/work-items/ORCH-075/01-brd.md`
- TRZ: `docs/work-items/ORCH-075/02-trz.md` (ground-truth таблица FR-1, секции FR-2.1)
- Acceptance: `docs/work-items/ORCH-075/03-acceptance-criteria.md`
- Tech-risks: `docs/work-items/ORCH-075/10-tech-risks.md`
- Глобальный реестр: `docs/architecture/adr/adr-0019-pipeline-docs-standard.md`
- Эталоны скелетов: ORCH-088 / ORCH-073 / ORCH-089 / ORCH-071 (`docs/work-items/*/`)
- Сверено по коду: `src/stages.py` (`STAGE_TRANSITIONS`), `src/qg/checks.py` (`QG_CHECKS`,
  `_parse_*`), `src/stage_engine.py`.
