192 lines
21 KiB
Markdown
192 lines
21 KiB
Markdown
---
|
||
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`).
|