--- work_item: ORCH-105 stage: analysis author_agent: analyst status: ready-for-review created_at: 2026-06-12 model_used: claude-opus-4-8 --- # 01 — BRD (бизнес-требования): ORCH-105 — Подготовка презентации по орку Work Item: **ORCH-105** · Repo: **orchestrator** · Стадия: analysis ## 1. Бизнес-контекст и проблема Заказчику нужна **презентация о продукте «Orchestrator» в формате PowerPoint** — чтобы показывать платформу стейкхолдерам и потенциальным заказчикам. Дополнительно в презентацию надо добавить **слайд про Lite-установку** (через скрипты-установщики) и **слайды-инструкцию «как пользоваться орком через Plane»**. **Установленный факт (опора, не изобретать):** канон презентации в репозитории **уже существует** — его ввела задача **ORCH-011** (витрина системы `docs/overview/`): - `docs/overview/presentation.md` — **слайдо-источник** (источник истины): 16 слайдов в формате `## Слайд N: Заголовок` + 3–6 тезисов + опциональная подпись `> Визуал: …`. - `scripts/build_presentation.py` — dev-скрипт сборки **редактируемого `.pptx`** в тёмном дизайне (`python-pptx`, ленивый импорт; чистый парсер `parse_slides` — stdlib-only). - `tests/test_system_docs.py` — анти-дрейф-контур, который машинно валидирует формат слайдов, сквозную нумерацию, обязательные биты нарратива и процедуру сборки. Канон **намеренно** держит инварианты (ORCH-011 D4/D5, NFR-2): сборка идёт **вне рантайма платформы** (одноразовый dev-venv), `python-pptx` **не входит** в прод-образ, а **собранный `.pptx`-бинарь в git не коммитится** (`build/` в `.gitignore`). **Проблема (дельта ORCH-105):** текущая дека рассказывает про продукт в целом, но **не содержит** (а) выделенного слайда о том, как просто развернуть Lite-вариант скриптами, и (б) слайдов-инструкции для оператора «как вести задачу через Plane» (запуск, статусы, человеческие гейты, авто-лейблы, STOP, наблюдение). Задача — **дополнить существующий слайдо-источник** этим содержанием и убедиться, что `.pptx` собирается с новыми слайдами. Это **docs-only** доработка контента витрины: код рантайма не меняется. ## 2. Объём (scope) ### В объёме - **Расширить `docs/overview/presentation.md`:** - добавить **один выделенный слайд про Lite-установку** (скрипт-ассистированный характер: `gen_secrets.py` → секреты, `onboard_project.py` → регистрация проекта, `docker compose up`, пошаговый runbook `LITE_SETUP.md` с проверкой каждого шага); - добавить **2–3 слайда-инструкцию «как пользоваться орком через Plane»** (запуск задачи, статусная модель «индикация ≠ управление», два человеческих гейта — Approved и Confirm Deploy, авто-лейблы `autoApprove`/`autoDeploy`/`Bug`, отмена STOP, наблюдение за ходом); - при необходимости — лёгкая актуализация продуктового нарратива на текущее состояние. - Сохранить **сквозную нумерацию слайдов с 1** (renumber при вставке в середину) и формат (заголовок + 3–6 тезисов + опц. `> Визуал:`), а также раздел «Как собрать .pptx». - Убедиться, что `scripts/build_presentation.py` собирает валидный `.pptx`, включающий новые слайды (скрипт менять **не требуется** — парсер обобщённый; правка только при крайней необходимости). - **Расширить анти-дрейф** `tests/test_system_docs.py`: зафиксировать присутствие нового обязательного контента (Lite-установка, использование через Plane). - Обновить `CHANGELOG.md` (запись `docs:`); при необходимости — указатель/маршрут в `docs/overview/README.md`. ### Вне объёма - **Коммит собранного `.pptx`-бинаря в git** — запрещён каноном ORCH-011 D5 (`build/` в `.gitignore`); презентация собирается по требованию. - Добавление `python-pptx` в `requirements*`/`Dockerfile` (NFR-2; машинно запрещено тестом). - Кастомный графический дизайн/брендинг сверх существующего тёмного текстового шаблона (визуалы — текстовые подписи `> Визуал: …`, а не растровые картинки). - Переписывание дизайна рендера (`build_pptx`), смена темы/шрифтов — если это не строго необходимо. - Любые изменения рантайма: `src/**`, `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, схема БД — **не трогаются**. - Переписывание `business.md` и прочих тех-блоков витрины (описанные способности — тираж и работа через трекер — там уже отражены; ORCH-105 добавляет именно **слайды**). - Создание отдельного монолитного «lite-инсталлятора» как нового скрипта (его нет; Lite ставится комбинацией существующих скриптов и compose — см. §6). ## 3. Заинтересованные стороны - **Заказчик / Owner** — постановщик задачи и **приёмщик** презентации; конечный пользователь `.pptx` при показе стейкхолдерам. - **Потенциальные заказчики / менеджеры** — аудитория презентации (нетехнический и полу-технический читатель). - **Операторы платформы** — целевые читатели слайдов «как пользоваться через Plane». - **Reviewer** — контролирует норматив сопровождения витрины (изменил витрину → согласовано, факты не разъехались с golden sources; необновлённый сопутствующий док → finding ≥ P1). ## 4. Бизнес-требования (BR) - **BR-1** — Презентация о продукте в формате PowerPoint собирается из слайдо-источника витрины и содержит связный рассказ о платформе (существующий нарратив сохранён и при необходимости актуализирован). - **BR-2** — В презентации есть **выделенный слайд про Lite-установку**, точно отражающий её скрипт-ассистированный характер: секреты генерирует `scripts/gen_secrets.py`, проект регистрирует `scripts/onboard_project.py` (`plan`/`apply`/`verify`), стек поднимается `docker compose`, а маршрут описан пошаговым runbook `LITE_SETUP.md` с проверкой каждого шага. Без вымышленных артефактов/скриптов. - **BR-3** — В презентации есть **слайды-инструкция «как пользоваться орком через Plane»**, покрывающие: запуск задачи (перевод в «To Analyse» — единственная точка входа), статусную модель (индикация ≠ управление; управляющих статусов ровно три), **два человеческих гейта** (Approved на `analysis`, Confirm Deploy на `deploy`), **авто-лейблы** (`autoApprove`/ `autoDeploy`/`Bug`), **отмену STOP**, и **наблюдение за ходом** (статусы доски + живая карточка в Telegram + комментарии в задаче). - **BR-4** — Итоговый `.pptx` собирается документированной командой (`scripts/build_presentation.py`) и включает **все** новые слайды; тёмный дизайн и корректное отображение кириллицы сохранены. - **BR-5** — Содержание презентации **фактологически точно** и согласовано с golden sources витрины (`tech-pipeline.md`, `tech-integrations.md`, `LITE_SETUP.md`, паспорт `CLAUDE.md`): никаких выдуманных возможностей, имён статусов, лейблов или скриптов. - **BR-6** — Сопровождение выполнено в том же PR: `CHANGELOG.md` несёт запись `docs:` по ORCH-105; норматив витрины (ORCH-011/079) соблюдён. ## 5. Нефункциональные требования (NFR) - **NFR-1 (self-hosting безопасность)** — изменение **docs-only**: `src/**`, `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, схема БД — байт-в-байт не трогаются; `python-pptx` **не попадает** в прод-образ; сборка `.pptx` — только вне рантайма (dev-venv). - **NFR-2 (анти-дрейф / совместимость формата)** — после правок `presentation.md` остаётся валидной для канонического парсера `parse_slides` (сквозная нумерация с 1, ≥1 тезис на слайд, непустые заголовки); **весь существующий** `tests/test_system_docs.py` — зелёный. - **NFR-3 (бинарь не в git)** — собранный `.pptx` не коммитится; `build/` остаётся в `.gitignore`; артефакт сборки — по требованию. - **NFR-4 (гигиена)** — в слайдах **нет** боевых хост-литералов (FORBIDDEN-скан) и секретоподобных значений (секрет-эвристика); относительные ссылки резолвятся. - **NFR-5 (стиль)** — новые слайды держат стиль деки: 3–6 тезисов, опц. подпись `> Визуал: …`, тон и терминологию `business.md` (нетехнический язык для продуктовых слайдов; оператор-инструкция — простыми шагами). ## 6. Допущения и ограничения - **Форма поставки = воспроизводимая сборка.** Deliverable — **расширенный слайдо-источник + скрипт сборки**; сам `.pptx` производится по требованию (ORCH-011 D5). Если нетехническому стейкхолдеру нужен готовый файл — он **собирается командой и передаётся вне git** (например, вложением к задаче Plane); это операционный шаг, не изменение кода. Это сознательное следование действующему машинно-проверяемому канону, а не упущение. - **«Скрипт-установщик» для Lite** = фактические скрипты-помощники (`gen_secrets.py`, `onboard_project.py`) + `docker compose` + verified-runbook `LITE_SETUP.md`. **Отдельного монолитного lite-инсталлятора в репозитории нет**; одношаговый bootstrap (`bootstrap_bundle.py`) относится к варианту **Bundled**, а не Lite. Заказчик явно просил **Lite** — слайд остаётся точным к Lite (при желании можно одной строкой упомянуть Bundled-bootstrap как смежный вариант, но фокус слайда — Lite). - **Рост деки.** С добавлением ~4 слайдов (1 Lite + 2–3 Plane) дека вырастает до ~19–20 слайдов. Это выше «ориентира 14–18» из ORCH-011 FR-4, но **проходит жёсткий тест** (`≥ 12`). Рост оправдан явным запросом; финальное число и возможное слияние слайдов — на усмотрение developer/architect (жёсткое требование — только сквозная нумерация и ≥ 12). - **Сборка/проверка `.pptx`** предполагает доступность `python-pptx` в dev-venv (вне рантайма). **Автоматический гейт тестов проверяет ИСТОЧНИК** (`presentation.md`: парс/структура/контент), а **не отрендеренный бинарь** — рендер проверяется **вручную** в dev-venv (честное разграничение; см. 03/04). ## 7. Критерии успеха Расширенный слайдо-источник собирается в `.pptx`; слайды Lite-установки и использования через Plane присутствуют, точны и согласованы с golden sources; сквозная нумерация и формат сохранены; весь `tests/test_system_docs.py` (с новыми проверками) зелёный; `python-pptx` не в прод-образе, бинарь не в git; `CHANGELOG`/витрина обновлены. Детальные PASS/FAIL — `03-acceptance-criteria.md`. ## 8. Риски - **Ошибка перенумерации** при вставке слайдов в середину → падение проверки сквозной нумерации (`parse_slides`). - **Дрейф фактов**: слайд расходится с реальной возможностью/именем (статус/лейбл/скрипт). - **Случайный запрещённый литерал/секрет** в тексте слайда → красный анти-дрейф. - **Неточная подача Lite** как монолитного инсталлятора (его нет) → вводящий в заблуждение слайд. - **Раздувание деки** сверх читаемого объёма. Краткий перечень; детальная проработка и митигации — `10-tech-risks.md` (заполняет архитектор).