# 01 — BRD: ORCH-075 — ORCH-52b: стандарт документов (docs/_templates + манифест стадий + ADR-naming)

Work Item: **ORCH-075**
Repo: **orchestrator** (self-hosting)
Стадия: analysis
Заказчик: Owner / команда агентов оркестратора
Тип: documentation-standard (слой 1 эпика ORCH-52)

> Документ фиксирует **бизнес-требования** к созданию стандарта документов пайплайна.
> ORCH-52b — слой 1 («стандарт»): только документация (манифест + канонические шаблоны +
> конвенция ADR-naming). Любая принудительная проверка/валидатор/правка кода и промптов —
> вне scope (это ORCH-52c/52d). Источник истины для манифеста — фактические
> `STAGE_TRANSITIONS` / `QG_CHECKS` и реальные эталонные доки в репозитории, а не вымысел.

---

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

### 1.1. Текущее состояние (проверено в репо)
- Каталоги `docs/_templates/` и `docs/_standards/` **не существуют**.
- Агенты (`analyst` → `architect` → … → `deployer`) пишут номерные доки work item
  (`00-business-request.md` … `17-security-report.md`) «с нуля по памяти».
- Конвенция ADR-naming `06-adr/ADR-NNN-<kebab-slug>.md` фактически уже сложилась в репо,
  но **нигде не зафиксирована** как стандарт.

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

### 1.3. Почему именно стандарт (а не сразу валидатор)
Эпик ORCH-52 разбит на слои, чтобы **сначала зафиксировать договорённость (golden source
документации)**, а уже потом, отдельной задачей (52c), навешивать машинную проверку
frontmatter/шаблонов на гейте. Стандарт без кода — обратимый, низкорисковый, не трогает
работающий прод-конвейер (self-hosting). Это снижает групповой риск.

## 2. Объём (scope)

### 2.1. В объёме (ORCH-52b)
1. **Манифест** `docs/_standards/PIPELINE_DOCS.md`: таблица «стадия → документ» с
   владельцем-агентом, категорией (`required` / `when-applicable` / `optional`), стадией
   написания и гейтом/механизмом проверки — **сверенная с фактическими `QG_CHECKS` и
   `stage_engine`**.
2. **Канонические шаблоны** `docs/_templates/*` — скелеты (frontmatter при необходимости +
   обязательные секции) для всех номерных доков из реального набора.
3. **Конвенция ADR-naming** — зафиксировать сложившийся формат `06-adr/ADR-NNN-<kebab-slug>.md`
   (нумерация с `001`, где живёт, как формируется slug); раздел в манифесте/стандарте.
4. Ссылки на новый стандарт в `CLAUDE.md` и `docs/architecture/README.md`; запись в
   `CHANGELOG.md`.

### 2.2. Вне объёма (явно — это ORCH-52c / 52d)
- Frontmatter-валидатор в коде; writer-контракт; принудительная проверка наличия/структуры
  шаблонов на Quality Gate.
- Любые изменения `QG_CHECKS` / `STAGE_TRANSITIONS` / `check_*` / `src/stage_engine.py` /
  схемы БД.
- Правка системных промптов агентов (`.openclaw/agents/*`) — это слой 52d.
- Массовое приведение **уже существующих** доков прошлых задач к новому шаблону (ретро-фит).

## 3. Заинтересованные стороны
| Роль | Интерес |
|------|---------|
| Owner | Единообразие и аудитопригодность документации проекта |
| Агенты analyst/architect | Готовый скелет → меньше расхождений, быстрее старт |
| Агенты reviewer/tester/deployer | Предсказуемый frontmatter машинных доков |
| ORCH-52c (downstream) | Стандарт = база для frontmatter-валидатора/writer-контракта |

## 4. Бизнес-требования (BR)
| ID | Требование |
|----|------------|
| BR-1 | Создан `docs/_standards/PIPELINE_DOCS.md` — манифест, покрывающий **все** номерные доки реального набора (00,01,02,03,04,06,07,08,10,12,13,14,15,16,17) с владельцем-агентом и категорией. |
| BR-2 | Каждому `required` и `when-applicable` доку соответствует канонический шаблон в `docs/_templates/` (frontmatter при необходимости + обязательные секции). |
| BR-3 | Формат ADR-naming `06-adr/ADR-NNN-<kebab-slug>.md` зафиксирован в стандарте и совпадает с реальными ADR в репо. |
| BR-4 | Манифест и шаблоны **согласованы с фактическими эталонными доками** (ORCH-088/073/089/071): нет секций, которых никто не пишет, и наоборот; frontmatter-ключи машинных доков совпадают с тем, что реально парсят гейты. |
| BR-5 | Обновлены `CLAUDE.md` и `docs/architecture/README.md` со ссылкой на стандарт; добавлена запись в `CHANGELOG.md`. |
| BR-6 | Манифест отражает категорию проверки документа фактическим механизмом: какие доки несут machine-verdict frontmatter, читаемый гейтом, а какие информационные (не гейтятся). |

## 5. Нефункциональные требования (NFR)
| ID | Требование |
|----|------------|
| NFR-1 | **Нулевой риск для прода:** изменения — только под `docs/` (+ `CLAUDE.md`/`CHANGELOG.md`). Ни строки кода/гейтов. |
| NFR-2 | **Достоверность:** все утверждения манифеста о стадии/агенте/гейте проверяемы по `src/stages.py` / `src/qg/checks.py` / `src/stage_engine.py`. |
| NFR-3 | **Не изобретать:** шаблоны выведены из существующих эталонов, не из фантазии; новые секции не вводятся. |
| NFR-4 | **Читаемость:** манифест — на русском, в стиле существующей документации проекта; таблицы машиночитаемо-аккуратные. |
| NFR-5 | **Обратимость:** удаление новых файлов полностью откатывает изменение без следов в поведении системы. |

## 6. Допущения и ограничения
- Реальный набор номерных доков и их частота взяты из `docs/work-items/` (факты в описании
  задачи); считаем его авторитетным на момент задачи.
- Эталонные («golden») задачи для извлечения скелетов — ORCH-088, ORCH-073, ORCH-089, ORCH-071.
- `09-review.md` — legacy fallback (канон — `12-review.md`); в манифест как канон **не**
  вводится, при необходимости упоминается примечанием.
- Стадия `monitoring` для `16-post-deploy-log.md` — пост-`done` наблюдение (ORCH-021), не
  ребро `STAGE_TRANSITIONS`; манифест это отражает явно.

## 7. Критерии успеха
- Любой агент, открыв `docs/_standards/PIPELINE_DOCS.md`, понимает: какой документ он пишет
  на своей стадии, в какой категории, с каким frontmatter и где он проверяется.
- Для каждого `required`/`when-applicable` дока существует шаблон, который можно скопировать
  и заполнить без догадок о структуре.
- ADR-naming больше не «устная традиция», а записанная конвенция.
- Полный набор уточняющих PASS/FAIL — в `03-acceptance-criteria.md`.

## 8. Риски
Технические риски и митигейшн ведёт архитектор в `10-tech-risks.md`. Ключевой бизнес-риск —
**рассинхрон стандарта с кодом** (манифест описал гейт, которого нет, или наоборот): митигируется
NFR-2 (сверка с `src/`) и AC-1/AC-4.