orchestrator/docs/work-items/ORCH-105/01-brd.md

work_item, stage, author_agent, status, created_at, model_used

work_item	stage	author_agent	status	created_at	model_used
ORCH-105	analysis	analyst	ready-for-review	2026-06-12	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 (заполняет архитектор).