---
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-<slug>.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`).
