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)

Манифест docs/_standards/PIPELINE_DOCS.md: таблица «стадия → документ» с владельцем-агентом, категорией (required / when-applicable / optional), стадией написания и гейтом/механизмом проверки — сверенная с фактическими QG_CHECKS и stage_engine.
Канонические шаблоны docs/_templates/* — скелеты (frontmatter при необходимости + обязательные секции) для всех номерных доков из реального набора.
Конвенция ADR-naming — зафиксировать сложившийся формат 06-adr/ADR-NNN-<kebab-slug>.md (нумерация с 001, где живёт, как формируется slug); раздел в манифесте/стандарте.
Ссылки на новый стандарт в 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.

10 KiB Raw Blame History Unescape Escape