112 lines
10 KiB
Markdown
112 lines
10 KiB
Markdown
# 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.
|