---
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` (заполняет архитектор).
