orchestrator/docs/work-items/ORCH-011/02-trz.md

work_item, stage, author_agent, status, created_at, model_used

work_item	stage	author_agent	status	created_at	model_used
ORCH-011	analysis	analyst	ready-for-review	2026-06-11	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).