---
work_item: ORCH-011
stage: analysis
author_agent: analyst
status: ready-for-review
created_at: 2026-06-11
model_used: claude-opus-4-8
---

# 01 — BRD: ORCH-011 — Полная документация системы мультиагентов оркестратора (бизнес + тех, для людей и презентаций)

Work Item: **ORCH-011** · Repo: **orchestrator** (self-hosting) · Стадия: analysis
Заказчик: Владелец (Слава)
Тип: docs+tests (паттерн ORCH-102/103 — golden-source-документ + структурные анти-дрейф тесты; рантайм не трогается)

---

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

### 1.1. Цель
Описать работу **всей** мультиагентной системы оркестратора в **одном месте** — от бизнес-смысла
(зачем, какую проблему решает, что умеет) до технического устройства (архитектура, конвейер,
агенты, модель объектов, интеграции, качество, наблюдаемость). Документация нужна, чтобы:
1. **другие люди** (разработчики, заказчики, менеджеры проектов) могли разобраться, как работает
   оркестратор, не раскапывая 60+ work-item пакетов и 40 ADR;
2. на её основе **генерировать презентационные материалы** по использованию и возможностям
   (решение Владельца: слайды PowerPoint, стильный тёмный дизайн, точный рендеринг).

### 1.2. Корневая проблема — документация богатая, но фрагментированная
Установленные факты (проверено по дереву репо, не изобретать):

| Что есть | Где | Ограничение как «единого места» |
|----------|-----|---------------------------------|
| Паспорт проекта | `CLAUDE.md` | для агентов/разработчиков; плотный реестр доработок, не вводный текст |
| Тех-витрина | `README.md` | только технический уровень; обзор без бизнес-слоя |
| Бизнес-видение | `docs/PRODUCT_VISION.md` (v1.0, 2026-06-04) | «концепция развития» (vision), не описание текущего состояния; не покрывает тех-уровень |
| Детальная архитектура | `docs/architecture/README.md` (~1246 строк), `internals.md` | глубокий справочник для инженеров; нечитаем «с нуля» нетехническим читателем |
| Решения | `docs/architecture/adr/` (40 сквозных ADR) + per-work-item ADR | точечные решения, не цельная картина |
| Стандарты | `docs/_standards/` (PIPELINE_DOCS, HANDOFF_PROTOCOL, TRACEABILITY) | нормативы для агентов |
| Эксплуатация/тираж | `docs/operations/` (8 runbook'ов), `docs/deployment/` (LITE_SETUP, BUNDLED_SETUP) | операторские инструкции |
| История/уроки | `docs/history/`, `docs/epics/self-evolution.md` | сырьё, не витрина |

**Ни один** из этих документов не является единой точкой входа «бизнес + тех» для трёх целевых
аудиторий. Новому человеку (заказчику, менеджеру, новому разработчику) сегодня нужно собирать
картину из 5–8 разных мест с разной степенью детализации и разным языком. Презентацию о
возможностях системы собирать не из чего — нет слайдо-готового источника.

### 1.3. Почему сейчас
- Платформа достигла тиражируемости (ORCH-101/102/103: Lite- и Bundled-развёртывание у заказчика)
  — появился **внешний читатель** (заказчики-тестеры), которому нужно объяснять систему.
- Самовоспроизводящийся темп доработок (self-hosting) без единой витрины делает порог входа всё
  выше с каждой задачей.

### 1.4. Решения Владельца (из бизнес-запроса) — приняты как требования
| # | Решение |
|---|---------|
| D-1 | Формат презентационных материалов — **слайды PowerPoint**, стильный **тёмный дизайн**, точный рендеринг. |
| D-2 | Аудитория документации — **разработчики, заказчики, менеджеры проектов** (три явных маршрута чтения). |
| D-3 | Единое место — репозиторий orchestrator: `docs/` (+ возможно compiled-wiki — как опция, см. §2.2). |
| D-4 | Поддерживать в актуальном состоянии: документация обновляется **сразу после изменения функционала** (правило CLAUDE.md §2 распространяется на новую витрину). |

---

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

### 2.1. В объёме
- **Единая витрина системы** — новый связный раздел в `docs/` с одной точкой входа (индексом),
  покрывающий **два уровня**:
  - **Бизнес-уровень** (для нетехнических читателей и презентаций): зачем нужен оркестратор и
    какую проблему решает; что умеет (автономный конвейер «задача → прод», мультипроектность,
    самовосстановление, пакетный авто-режим, багфикс-трек, тиражируемость); ценность и
    возможности простым языком; сценарии использования.
  - **Технический уровень** (7 блоков, контент-карта — TRZ §3):
    1) архитектура — компоненты и их связи; 2) конвейер/стадии и гейты на переходах;
    3) агенты — 6 ролей, входы/выходы, артефакты, шаблоны; 4) структура объектов —
    Project/Work-Item, реестр проектов, jobs-очередь, события/дедуп, каноническая модель БД;
    5) интеграции — Plane, Gitea, LLM-модели, Telegram; 6) качество/безопасность;
    7) аналитика/наблюдаемость.
- **Маршруты чтения** для трёх аудиторий (D-2): «я заказчик / я менеджер / я разработчик —
  с чего начать и что читать дальше».
- **Презентационная основа** (D-1): слайдо-структурированный источник (последовательность
  слайдов: заголовок/тезисы/визуальный мотив) + воспроизводимый путь получения `.pptx` в тёмном
  дизайне. Выбор инструмента генерации — за архитектором (TRZ §3.4, OQ-2).
- **Норматив сопровождения**: правило «изменил функционал → обнови витрину в том же PR»
  зафиксировано в витрине и в правилах агентов (D-4; ось reviewer'а по обзорным докам уже
  существует — ORCH-079).
- **Анти-дрейф**: структурные pytest-тесты каркаса витрины (по образцу
  `tests/test_lite_setup_doc.py` / `test_bundled_setup_doc.py`): обязательные разделы, сверка
  карты стадий импортом `src/stages.py::STAGE_TRANSITIONS`, полнота 6 агентов, валидность
  внутренних ссылок, запрет секретов/хост-хардкодов.
- Обновление указателей: `README.md`, `CLAUDE.md` (ссылка на витрину), `CHANGELOG.md`.

### 2.2. Вне объёма (явно, не делать)
- **Любые изменения рантайма:** `src/**`, `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`,
  machine-verdict ключи, схема БД, compose/Dockerfile — байт-в-байт.
- **Compiled-wiki / внешняя вики-платформа** — вне объёма v1: репозиторий остаётся единственным
  источником истины («канон не форкается», паттерн ORCH-009 BR-2); экспорт в wiki — возможное
  развитие, фиксируется как открытый вопрос (TRZ §9 OQ-4), не реализуется.
- **Перенос вне-репозиторных источников в репо**: `tasks/orchestrator/STATUS.md`, `BACKLOG.md`,
  PROGRESS-журналы, дневники `memory/` физически в репозитории отсутствуют — они служат лишь
  затравками для содержания; сами файлы в гит не переносятся (внутренняя кухня, риск утечки
  контекста/секретов).
- **Переписывание/замена существующих golden sources** (`docs/architecture/README.md`,
  `internals.md`, стандарты `docs/_standards/`, deployment-доки): витрина ссылается на них,
  а не дублирует и не подменяет (анти-«второй источник истины», BR-4).
- **Автогенерация документации из кода** (doc-from-code, autodoc) — вне объёма.
- **Маркетинговые материалы за пределами PPTX-основы** (видео, лендинги, демо-стенды).
- Новые runtime-зависимости прод-образа (включая библиотеки генерации презентаций) — запрещено
  (NFR-2).

---

## 3. Заинтересованные стороны
- **Владелец/оператор (Слава)** — заказчик задачи; принимает витрину и презентационную основу;
  использует слайды для показа возможностей платформы.
- **Заказчики платформы** (внешние, включая тестеров Lite/Bundled-тиража ORCH-102/103) — читают
  бизнес-уровень и сценарии; смотрят презентацию.
- **Менеджеры проектов** — читают бизнес-уровень + конвейер/статусную модель (что видно в Plane,
  какие человеческие гейты есть).
- **Разработчики** (люди и агенты самого оркестратора) — входят через витрину в технический
  уровень и далее по ссылкам в golden sources.
- **Reviewer-агент конвейера** — контролирует соблюдение норматива сопровождения витрины
  (расширение оси «обзорные доки» ORCH-079).

---

## 4. Бизнес-требования (BR)

| ID | Требование | Связь |
|----|------------|-------|
| BR-1 | В `docs/` существует **единая точка входа** (индекс витрины), из которой достижимы оба уровня (бизнес/тех) и все 7 тех-блоков; любой из трёх читателей начинает с одного места. | D-3, AC-1 |
| BR-2 | **Бизнес-уровень** читается нетехническим человеком: проблема → решение → ценность → возможности → сценарии использования; термины конвейера объяснены по-человечески; без необъяснённого жаргона и кодовых идентификаторов в основном тексте. | D-2, AC-2 |
| BR-3 | **Технический уровень** покрывает все 7 заявленных блоков (§2.1) и соответствует фактическому коду/канону репо: карта стадий = `STAGE_TRANSITIONS`, реестр гейтов = `QG_CHECKS` + под-гейты, агенты = 6 промптов `.openclaw/agents/` + таблица модель/эффорт (ORCH-41), модель данных = фактические таблицы `src/db.py`. | AC-3, AC-4, AC-5 |
| BR-4 | **Link-first / не форкается канон:** витрина даёт цельную картину и ссылается на golden sources за деталями (architecture/README, internals, стандарты, ADR, deployment-доки); не создаёт второй источник истины и не противоречит коду. | §2.2, AC-6 |
| BR-5 | **Презентационная основа:** в репо есть слайдо-структурированный источник (бизнес-нарратив → слайды) и воспроизводимый, документированный путь получения `.pptx` в тёмном дизайне (D-1). Инструмент — выбор архитектора; запуск — вне рантайма конвейера. | D-1, AC-7 |
| BR-6 | **Маршруты аудиторий:** витрина содержит явные маршруты чтения для заказчика / менеджера / разработчика (D-2). | D-2, AC-8 |
| BR-7 | **Норматив сопровождения:** правило «изменил функционал → обнови витрину в том же PR» зафиксировано в витрине и видимо агентам (CLAUDE.md-указатель); reviewer-ось обзорных доков покрывает витрину. | D-4, AC-9 |
| BR-8 | **Анти-дрейф:** каркас витрины и её ключевые машинно-проверяемые факты (стадии, агенты, ссылки, отсутствие секретов) защищены структурными pytest-тестами; их падение ловит расхождение витрины с кодом. | AC-10 |
| BR-9 | Существующие указатели актуализированы: `README.md` и `CLAUDE.md` ссылаются на витрину; `CHANGELOG.md` несёт запись. | AC-11 |

---

## 5. Нефункциональные требования (NFR)

| ID | Требование |
|----|------------|
| NFR-1 | **docs+tests only:** `src/**` байт-в-байт; `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict ключи / схема БД / compose / Dockerfile — не тронуты. Kill-switch не нужен: документация не исполняется (паттерн ORCH-102/103). |
| NFR-2 | **Прод-образ без новых зависимостей:** генерация презентации (если скриптом) исполняется вне рантайма (host/dev-окружение, явный запуск человеком — паттерн ORCH-009); зависимости генерации НЕ попадают в `requirements`/образ оркестратора. |
| NFR-3 | **Без секретов и хост-специфики** в новых доках/источниках презентации: токены, внутренние URL/имена хостов — только плейсхолдерами (паттерн `tests/test_no_host_hardcodes.py` / fenced-скан `test_lite_setup_doc.py`). |
| NFR-4 | **Язык:** русский (канон репо; языковое исключение deployer.md не затрагивается). Терминология единая со статусной моделью Plane (ORCH-066) и PIPELINE_DOCS. |
| NFR-5 | **Self-hosting safety:** задача не рестартит/не роняет прод-контейнер; прод-деплой — только штатным маршрутом конвейера (staging-гейт + Confirm Deploy). |
| NFR-6 | **Поддерживаемость:** витрина модульная (отдельные файлы по блокам, связанные индексом), чтобы будущие правки были точечными; объём основного текста разумен за счёт link-first (BR-4). |

---

## 6. Допущения и ограничения
- **Вне-репозиторные затравки** (`tasks/orchestrator/STATUS.md`, `BACKLOG.md`, PROGRESS-журналы,
  `memory/`) в worktree недоступны — содержание витрины строится из **внутрирепозиторных** golden
  sources (CLAUDE.md, README, PRODUCT_VISION, architecture/, _standards/, ADR, deployment/,
  history/). Этого достаточно: репо самодостаточен по фактам (проверено §1.2).
- `docs/PRODUCT_VISION.md` остаётся самостоятельным vision-документом; витрина переиспользует его
  бизнес-нарратив со сверкой с фактическим состоянием (что из vision уже реализовано — например,
  тираж ORCH-101/102/103) и ссылается на него.
- Точное имя/структура каталога витрины — решение архитектора (рекомендация TRZ §2: новый каталог
  в `docs/`, например `docs/overview/`); анти-дрейф тесты пишутся под выбранные пути.
- Бинарный артефакт `.pptx`: коммит бинаря в git спорен — решает архитектор (OQ-3); требование
  BR-5 — воспроизводимость пути генерации, не обязательность бинаря в репо.
- Задача объёмная по контенту: допускается реализация витрины «вглубь по блокам» в одном PR
  (один прогон developer); если объём не помещается — эскалация на уровне задач (разбиение)
  по штатному маршруту, не молчаливое сокращение объёма.

---

## 7. Критерии успеха (резюме; детали — 03-acceptance-criteria.md)
- AC-1 единая точка входа существует и связывает оба уровня и маршруты аудиторий.
- AC-2 бизнес-уровень самодостаточен для нетехнического читателя.
- AC-3…AC-5 тех-уровень покрывает 7 блоков и сходится с кодом (стадии/гейты/агенты/модель данных).
- AC-6 link-first: ссылки на golden sources валидны, дублирования-противоречий нет.
- AC-7 презентационная основа есть; путь к `.pptx` (тёмный дизайн) воспроизводим и документирован.
- AC-8 маршруты трёх аудиторий присутствуют.
- AC-9 норматив сопровождения зафиксирован.
- AC-10 структурные анти-дрейф тесты существуют и зелёные; полный pytest зелёный.
- AC-11 README/CLAUDE.md/CHANGELOG обновлены; `src/**` не тронут.

---

## 8. Риски (кратко; детали — 10-tech-risks.md, заполняет архитектор)
- **R-1 — гниение витрины.** Self-hosting темп (несколько задач в неделю) быстро устаревает любой
  снапшот. Митигция: link-first (BR-4) + норматив сопровождения (BR-7) + структурные тесты на
  машинно-проверяемые факты (BR-8) — дрейф ловится CI, а не глазами.
- **R-2 — второй источник истины.** Дублирование деталей architecture/README в витрине приведёт к
  противоречиям. Митигция: витрина = картина + ссылки; детали живут в существующих golden sources.
- **R-3 — объём одного прогона.** Полная витрина + презентация + тесты могут не поместиться в один
  PR разумного размера. Митигция: модульность (NFR-6), приоритет блоков, при необходимости —
  эскалация/разбиение (допущение §6).
- **R-4 — зависимость генерации презентации.** Библиотека генерации PPTX в прод-образе — лишний
  attack-surface/вес. Митигция: NFR-2 (вне рантайма), решение по инструменту — ADR архитектора.
- **R-5 — расползание скопа в маркетинг.** Слайды → «а давайте ещё видео/лендинг». Митигция:
  жёсткая граница §2.2.
