--- work_item: ORCH-011 stage: analysis author_agent: analyst status: ready-for-review created_at: 2026-06-11 model_used: claude-opus-4-8 --- # 02 — ТЗ (TRZ): ORCH-011 — Полная документация системы мультиагентов оркестратора Work Item: **ORCH-011** · Repo: **orchestrator** · Стадия: analysis > ТЗ описывает **что** должно появиться/измениться и **где** (файлы, структура, контент-карта, > источники истины). **Как** (точное имя каталога витрины, инструмент генерации PPTX, разбиение > на файлы) — решает архитектор в `06-adr/`. Тип изменения — **docs+tests** (паттерн > ORCH-102/103): рантайм не трогается. --- ## 1. Сводка изменения Создать в `docs/` **единую витрину системы** — связный набор документов с одной точкой входа, описывающий мультиагентный оркестратор на двух уровнях (бизнес + технический, 7 блоков), с маршрутами чтения для трёх аудиторий (разработчики / заказчики / менеджеры), слайдо-готовой презентационной основой (PowerPoint, тёмный дизайн) и нормативом сопровождения. Каркас и машинно-проверяемые факты витрины защитить структурными pytest-тестами (анти-дрейф). Обновить указатели (`README.md`, `CLAUDE.md`, `CHANGELOG.md`). `src/**` — байт-в-байт. --- ## 2. Задействованные модули / пути | Путь | Действие | |------|----------| | `docs/<витрина>/` (рекомендация: `docs/overview/`; финальное имя — ADR архитектора) | **создать**: индекс + бизнес-часть + тех-часть (7 блоков) + маршруты аудиторий + презентационная основа | | `docs/<витрина>/README.md` (или `index.md` — по ADR) | **создать**: единая точка входа (BR-1) | | `tests/test_system_docs.py` (имя — по паттерну `test_lite_setup_doc.py`; финал — ADR) | **создать**: структурный анти-дрейф витрины (FR-7) | | `scripts/` (опционально, по ADR — например `scripts/build_presentation.py`) | **создать (опц.)**: генерация `.pptx` из презентационной основы (FR-4) | | `README.md` | изменить: ссылка на витрину (раздел-указатель) | | `CLAUDE.md` | изменить: указатель на витрину + норматив сопровождения (FR-6) | | `CHANGELOG.md` | изменить: запись `docs:` | | `docs/PRODUCT_VISION.md` | НЕ переписывать; допустима врезка-ссылка на витрину | | `src/**`, `docker-compose.yml`, `Dockerfile`, `requirements*` | **НЕ трогать** (NFR-1, NFR-2) | Чтение (источники истины для контента, без изменения): `src/stages.py`, `src/qg/checks.py`, `src/db.py`, `src/projects.py`, `src/plane_sync.py`, `src/notifications.py`, `src/queue_worker.py`, `src/agents/launcher.py`, `.openclaw/agents/*.md`, `docs/architecture/README.md`, `internals.md`, `docs/_standards/*`, `docs/architecture/adr/*`, `docs/deployment/*`, `docs/operations/*`, `docs/PRODUCT_VISION.md`. --- ## 3. Функциональные требования ### FR-1 — Единая точка входа и каркас витрины (BR-1, NFR-6) - Новый каталог в `docs/` с индекс-документом, который: (а) в 1–2 абзацах отвечает «что это за система»; (б) ведёт на бизнес-часть и тех-часть; (в) несёт маршруты чтения трёх аудиторий (FR-5); (г) несёт норматив сопровождения (FR-6). - Витрина модульная: отдельные файлы по частям/блокам, связанные индексом (а не один монолит) — точечные правки в будущем дешевле. Точная разбивка — ADR. - Все внутренние ссылки — относительные, валидные (проверяется тестом FR-7). ### FR-2 — Бизнес-уровень (BR-2) Содержание (для нетехнического читателя; источники: `docs/PRODUCT_VISION.md` §1–2, `README.md`, `CLAUDE.md` TL;DR — со сверкой с фактическим состоянием кода): - **Проблема и решение:** люди-бутылочное-горлышко в передачах между ролями → конвейер ИИ-агентов «постановка → прод», человек = постановщик и приёмщик. - **Что умеет (фактическое состояние, не vision):** автономный конвейер задача→прод с гейтами качества; мультипроектность (несколько репо из одного инстанса); самовосстановление (reconciler / job-reaper / watchdog'и / sidecar); пакетный авто-режим (serial gate ORCH-088 + autoApprove/autoDeploy ORCH-089); дешёвый багфикс-трек (ORCH-019); отмена задач (STOP, ORCH-090); наблюдаемость (живая Telegram-карточка, `/queue`, `/metrics`, журнал уроков); самообслуживание (self-hosting — платформа дорабатывает себя); тиражируемость (Lite/Bundled, ORCH-101/102/103). - **Ценность простым языком:** скорость / стоимость / автономность / надёжность / масштаб (переиспользовать формулировки PRODUCT_VISION, сверив цифры с реальностью; цифры без подтверждения в репо не изобретать). - **Сценарии использования** (минимум): «фича за вечер» (полный цикл с человеческими гейтами Approved / Confirm Deploy); «багфикс по короткому маршруту» (метка Bug); «пакет задач на ночь» (serial gate + авто-лейблы); «несколько проектов параллельно»; «развернуть платформу у себя» (Lite/Bundled); «остановить задачу» (STOP). - Кодовые идентификаторы (`ORCH-NNN`, имена функций) в основном бизнес-тексте не используются; допустимы сноски/ссылки. ### FR-3 — Технический уровень: 7 блоков с контент-картой (BR-3, BR-4) Каждый блок: цельное изложение + ссылки на golden source за деталями. Обязательная привязка к фактам кода (источники указаны; не дублировать детали сверх необходимого — link-first): | # | Блок | Обязательное содержание | Источник истины (ссылаться) | |---|------|------------------------|------------------------------| | 1 | Архитектура | компоненты и связи: FastAPI-приём вебхуков (Plane/Gitea, HMAC, дедуп), очередь jobs + worker, stage-engine, agent launcher (Claude CLI, git worktree), QG-реестр, plane-sync, notifications, фоновые демоны (reconciler, job-reaper, disk-watchdog, build-cache-pruner), sidecar-watchdog; одна диаграмма потока «вебхук → очередь → агент → гейт → переход» | `docs/architecture/README.md` «Компоненты», `internals.md`, `src/main.py` lifespan | | 2 | Конвейер/стадии | схема `created → analysis → architecture → development → review → testing → deploy-staging → deploy → done` (+ `cancelled`-сток); exit-гейты рёбер; под-гейты ребра `deploy-staging→deploy` (security → merge → coverage → image-freshness) и `deploy→done` (merge-verify) как врезки, не стадии; откаты REQUEST_CHANGES (max 3); человеческие гейты (Approved BRD, Confirm Deploy) и их снятие авто-лейблами; багфикс-маршрут (пропуск architecture); serial gate / freeze; статусная модель Plane = индикация ≠ управление | `src/stages.py::STAGE_TRANSITIONS`, `src/qg/checks.py::QG_CHECKS`, `docs/_standards/PIPELINE_DOCS.md` §1–3, CLAUDE.md (ORCH-059/066/088/089/019/090) | | 3 | Агенты | 6 ролей (analyst/architect/developer/reviewer/tester/deployer): задача роли, вход/выход, артефакты по стадиям, machine-verdict ключи; таблица модель/эффорт (резолв из config, ORCH-41/74/81); канон промптов (5 XML-секций, 52d) и где лежат промпты; handoff-протокол | `.openclaw/agents/*.md`, `docs/_standards/PIPELINE_DOCS.md` §2, `HANDOFF_PROTOCOL.md`, таблица моделей `docs/architecture/README.md` | | 4 | Структура объектов | каноническая модель: Project (реестр `projects.py`: plane-project → repo+prefix) → Work-Item/Task (`tasks`: stage, track, ветка) → Jobs (очередь: статусы, atomic claim, deps, ретраи/backoff/breaker) → Agent-runs (стоимость/токены/effort) → события вебхуков и дедуп → вспомогательные таблицы (`repo_freeze`, `coverage_baseline`, `tracker_messages`, `lessons`); словарь терминов (стадия/гейт/под-гейт/job/worktree/lease) | `src/db.py` (фактические таблицы), `src/projects.py`, `internals.md` «Database Schema», ADR соответствующих задач | | 5 | Интеграции | Plane (issues/states/labels/webhooks; статусная модель ORCH-066; вход конвейера «To Analyse»); Gitea (репо/ветки/PR; merge строго через PR-API — INV-4; merge-актор с retry ORCH-093; CI `check_ci_green`); LLM (Claude CLI, `--model`/`--effort` из config); Telegram (live-карточка bump-режима, алерты; sidecar-канал отдельно) | `src/plane_sync.py`, `src/webhooks/*`, `src/merge_gate.py`, `src/agents/launcher.py`, `src/notifications.py`, CLAUDE.md (ORCH-042/067/087/093) | | 6 | Качество/безопасность | философия Quality Gates: машинные вердикты только из YAML-frontmatter (никогда проза), единый контракт `src/frontmatter.py`; реестр гейтов и что каждый ловит; security-гейт (ORCH-022) и coverage-гейт с baseline-ratchet (ORCH-027); канон секретов (.env, не в гит; `gen_secrets.py`); self-hosting-страховки (staging 8501, Confirm Deploy, запрет force-push в main, никогда не ронять прод) | `src/qg/checks.py`, `src/frontmatter.py`, `docs/_standards/PIPELINE_DOCS.md` §3, CLAUDE.md «Self-hosting», `docs/operations/INFRA.md` | | 7 | Аналитика/наблюдаемость | живая Telegram-карточка задачи (стадии, модель/эффорт, стоимость/токены, честные метрики времени); `GET /queue` (снимки всех подсистем: serial_gate, auto_labels, bug_fast_track, coverage, lessons, reaper, reconcile, …); `GET /metrics` (машинный контракт для sidecar, schema_version); sidecar-watchdog (наблюдатель отделён от наблюдаемого); журнал уроков `lessons` (фундамент петли самообучения); стоимость по агентам (`agent_runs`) | `src/metrics.py`, `src/notifications.py`, `src/lessons.py`, `docs/architecture/README.md` (§ /metrics, § sidecar), CLAUDE.md (ORCH-098/099/100) | - **Согласованность с кодом обязательна:** перечень стадий, имена гейтов, имена агентов, имена таблиц в витрине должны совпадать с фактическими (`src/stages.py`, `src/qg/checks.py`, `src/db.py`); расхождение — дефект (ловится FR-7 и reviewer'ом). ### FR-4 — Презентационная основа и путь к PPTX (BR-5, D-1) - В витрине есть **презентационный источник**: упорядоченная последовательность слайдов (рекомендация: markdown с явной слайдо-структурой — «слайд N: заголовок / 3–5 тезисов / подпись-визуал»), покрывающая бизнес-нарратив (проблема → решение → как работает → возможности → сценарии → тираж → статус платформы). Объём — ориентир 12–20 слайдов (финал — у архитектора). - Зафиксирован **воспроизводимый путь** получения `.pptx` в тёмном дизайне: либо скрипт в `scripts/` (запуск вне рантайма, host/dev-окружение), либо документированная ручная процедура поверх источника. Выбор инструмента (python-pptx / Marp→pptx / иное) и факт коммита бинаря — решение архитектора (OQ-2, OQ-3). Требования к пути: тёмная тема, кириллица рендерится точно, процедура описана пошагово с проверкой результата (паттерн «команда + Проверка:» из LITE_SETUP). - Зависимости генерации **не** попадают в прод-образ/`requirements` оркестратора (NFR-2). ### FR-5 — Маршруты аудиторий (BR-6, D-2) - Индекс несёт три явных маршрута: **заказчик** (бизнес-часть → сценарии → презентация → Lite/Bundled-доки), **менеджер** (бизнес-часть → конвейер и статусная модель Plane → человеческие гейты → наблюдаемость), **разработчик** (тех-часть → architecture/README → internals → стандарты → ADR-реестр → CLAUDE.md). ### FR-6 — Норматив сопровождения (BR-7, D-4) - В витрине (индексе) — явная норма: «изменил функционал → обнови витрину в том же PR» (формулировка по образцу NFR-5 ORCH-102/103). - `CLAUDE.md` — краткий указатель на витрину в существующем правиле документации (§2 правил агентов); reviewer-ось «обзорные доки» (ORCH-079) распространяется на витрину — фиксируется формулировкой в витрине/ADR (изменение промпта reviewer'а НЕ требуется, если ось уже сформулирована обобщённо — проверить при реализации; если требуется правка промпта, она следует канону 52d и анти-регресс тестам `test_agent_prompts_canon.py`). ### FR-7 — Структурный анти-дрейф (BR-8) Новый тест-модуль (паттерн `tests/test_lite_setup_doc.py` / `test_bundled_setup_doc.py` / `test_orch_52b_docs_standard.py`; без сети/LLM/subprocess): - наличие файлов витрины и обязательных разделов индекса (вкл. маршруты 3 аудиторий и норматив сопровождения); - **сверка карты стадий** в витрине импортом `src.stages.STAGE_TRANSITIONS` (полнота и порядок — как тест полноты `_STAGE_STATUS_LABEL` ORCH-091: derive из кода, не статичный список); - **полнота 6 агентов** (analyst/architect/developer/reviewer/tester/deployer) в блоке агентов; - валидность относительных внутренних ссылок витрины (целевые файлы существуют); - FORBIDDEN-скан новых доков/презент-источника: запрещённые хост-литералы (импорт списка из `tests/test_no_host_hardcodes.py`, как делает `test_lite_setup_doc.py`) + секрет-эвристика; - наличие ссылки на витрину в `README.md`. --- ## 4. Изменения API **Нет.** Эндпоинты/вебхуки не добавляются и не меняются. ## 5. Изменения схемы БД **Нет.** Таблицы/миграции не вводятся. ## 6. Требования к новым/изменённым QG checks **Нет.** Реестр `QG_CHECKS`/`check_*` не меняется. Анти-дрейф витрины — обычные pytest-тесты в `tests/` (исполняются существующими гейтами `check_ci_green`/`check_tests_passed`/coverage-гейтом штатно), **не** новый Quality Gate. ## 7. Совместимость / регресс - **Нулевая регрессия рантайма по построению:** меняются только `docs/**`, `tests/**`, `README.md`, `CLAUDE.md`, `CHANGELOG.md` (+ опц. `scripts/`); `src/**` байт-в-байт. Kill-switch не нужен — документация и dev-скрипт не исполняются конвейером (паттерн ORCH-009/102/103). - Существующие тесты остаются зелёными; новые тесты аддитивны. - enduro-trails не затрагивается (общих артефактов нет). - Откат = revert PR (доки/тесты), без операционных последствий. - Self-hosting: прод-контейнер не рестартится в рамках задачи; выкат — штатным маршрутом. --- ## 8. Артефакты pipeline (создать/обновить в ТОМ ЖЕ PR разработки) - Витрина `docs/<…>/` (FR-1…FR-5) + презентационный источник. - `tests/test_system_docs.py` (FR-7). - `README.md` (ссылка), `CLAUDE.md` (указатель + норматив), `CHANGELOG.md` (`docs:`-запись). - ADR архитектора: `docs/work-items/ORCH-011/06-adr/ADR-001-.md` (структура витрины, инструмент PPTX, политика бинаря, состав тестов); при сквозной значимости — зеркало в `docs/architecture/adr/`. --- ## 9. Открытые вопросы для архитектора (не блокируют анализ) - **OQ-1:** Имя и внутренняя структура каталога витрины (`docs/overview/` vs `docs/system/`; один индекс + N файлов блоков vs два файла «business/tech»). Рекомендация аналитика — `docs/overview/` с индексом и помодульными файлами (NFR-6). - **OQ-2:** Инструмент генерации PPTX: скрипт `scripts/` (python-pptx; host/dev-venv, вне прод-образа) vs конвертация из markdown (Marp и т.п.) vs документированная ручная процедура. Критерии: тёмная тема, точный рендеринг кириллицы, воспроизводимость, NFR-2. - **OQ-3:** Коммитить ли собранный `.pptx` в репо (бинарь в git) или хранить только источник + процедуру сборки. - **OQ-4:** Compiled-wiki/экспорт (упомянут в бизнес-запросе как «возможно»): фиксируем вне объёма v1; нужно ли заводить follow-up work item. - **OQ-5:** Достаточна ли текущая формулировка reviewer-оси обзорных доков (ORCH-079) для покрытия витрины, или нужна точечная правка промпта reviewer (тогда — по канону 52d, с обновлением `test_agent_prompts_canon.py`).