--- 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.