---
work_item: ORCH-105
stage: analysis
author_agent: analyst
status: ready-for-review
created_at: 2026-06-12
model_used: claude-opus-4-8
---

# 02 — ТЗ (TRZ): ORCH-105 — Подготовка презентации по орку

Work Item: **ORCH-105** · Repo: **orchestrator** · Стадия: analysis

> ТЗ описывает **конкретные изменения к реализации**, выведенные из BRD и фактического кода.
> Архитектурное обоснование/решения — задача архитектора (06-adr).

## 1. Сводка изменения

**Docs-only** доработка контента витрины. Расширяем существующий слайдо-источник
`docs/overview/presentation.md` (канон ORCH-011) тремя смысловыми блоками: (1) выделенный
слайд про **Lite-установку** скриптами; (2) 2–3 слайда-инструкция **«как пользоваться орком
через Plane»**; (3) при необходимости — точечная актуализация нарратива. Сохраняем формат и
сквозную нумерацию слайдов, раздел сборки `.pptx` и тёмный дизайн. Дополняем анти-дрейф
`tests/test_system_docs.py`, чтобы новый обязательный контент был зафиксирован машинно.
Скрипт сборки `scripts/build_presentation.py` менять **не требуется** (парсер обобщённый).
Рантайм (`src/**`, стадии, гейты, БД) — **не затрагивается**.

## 2. Задействованные модули / пути

| Путь | Действие |
|------|----------|
| `docs/overview/presentation.md` | **изменить** — добавить слайд Lite + 2–3 слайда Plane-usage; перенумеровать сквозно; сохранить раздел «Как собрать .pptx»; опц. актуализировать нарратив |
| `tests/test_system_docs.py` | **изменить** — добавить assert'ы присутствия нового обязательного контента (Lite-установка, использование через Plane); существующие проверки сохранить зелёными |
| `CHANGELOG.md` | **изменить** — запись `docs:` по ORCH-105 |
| `docs/overview/README.md` | **опц.** — указатель/строка маршрута (если уместно); не обязателен |
| `scripts/build_presentation.py` | **НЕ изменять** — `parse_slides` обобщён; правка только при крайней необходимости (тогда сохранить ленивый импорт `pptx` и stdlib-only top-level) |
| `build/orchestrator-overview.pptx` | **НЕ коммитить** — артефакт сборки (`build/` в `.gitignore`, ORCH-011 D5) |
| `requirements*.txt`, `Dockerfile` | **НЕ изменять** — `python-pptx` не добавлять (NFR-2) |

## 3. Функциональные требования

### FR-1 — Слайд про Lite-установку (BR-2)
Добавить **один** слайд (формат `## Слайд N: <Заголовок>` + 3–6 тезисов + опц. `> Визуал:`),
точно отражающий Lite-маршрут по `docs/deployment/LITE_SETUP.md`:
- Lite = **два контейнера платформы** (`orchestrator` + `orchestrator-watchdog`) на
  инфраструктуре заказчика; свои Plane / Gitea / Telegram / LLM подключаются (не входят в Lite).
- Разворачивается **без правки кода — только конфиг** (принцип 10-common, ORCH-101).
- Скрипты-помощники: `scripts/gen_secrets.py` (свежие секреты), `scripts/onboard_project.py`
  (`plan`/`apply`/`verify` — регистрация проекта заказчика); подъём — `docker compose up -d`.
- Маршрут — **пошаговый runbook** `LITE_SETUP.md` с **проверкой каждого шага** (PASS/FAIL).
- **Рекомендуемое размещение:** сразу после текущего слайда «Тираж платформы» (обзор Lite/
  Bundled) — как его углубление. Точная позиция — на усмотрение developer (требование жёсткое
  только к сквозной нумерации).
- **Точность (BR-5):** не называть Lite «одним монолитным инсталлятором»; одношаговый
  bootstrap — это Bundled (`bootstrap_bundle.py`), упоминание опционально и как **смежный**
  вариант.

### FR-2 — Слайды «как пользоваться орком через Plane» (BR-3)
Добавить **2–3** слайда оператор-инструкции, опираясь на `docs/overview/tech-pipeline.md`
(человеческие гейты, STOP, статусная модель) и `tech-integrations.md` (Plane). Покрыть:
- **Запуск:** перевод задачи в статус **«To Analyse»** — единственная точка входа в конвейер.
- **Статусная модель:** статусы Plane — **индикация, не управление**; платформа сама их
  выставляет; управляющих статусов ровно три (запуск, человеческие гейты, STOP).
- **Два человеческих гейта:** **Approved** на `analysis` (одобрить постановку) и **Confirm
  Deploy** на `deploy` (подтвердить прод-выкладку — отдельный статус, чтобы привычный approve
  не выкатывал прод случайным кликом).
- **Авто-лейблы:** `autoApprove` / `autoDeploy` (снимают человеческие гейты, пакетный
  авто-режим — но **ни одна техническая проверка не пропускается**); `Bug` (багфикс-маршрут).
- **Отмена:** статус **STOP** — безопасная отмена с уборкой (ветка/worktree), `cancelled`;
  STOP не трогает `main`/прод-контейнер.
- **Наблюдение за ходом:** платформа двигает статусы доски (Backlog → … → Done) + **живая
  карточка в Telegram** (стадия, стоимость, время, кликабельный номер задачи) + комментарии в
  задаче со ссылками на ветку/PR.
- **Рекомендуемое размещение:** связным кластером после слайда «Человек в контуре» (он вводит
  «два решения человека») и/или рядом со «Сценарии использования». Точная позиция — на
  усмотрение developer.

### FR-3 — Формат и сквозная нумерация (NFR-2)
- Слайды нумеруются **сквозно с 1** без пропусков (вставка в середину ⇒ перенумеровать все
  последующие). Это машинно-проверяемо: `tests/test_system_docs.py::
  test_presentation_source_parses_with_canonical_parser` требует
  `[s.number] == list(range(1, N+1))`.
- Каждый новый слайд: **непустой заголовок** + **3–6 тезисов** (минимум — ≥1, требует тест) +
  опц. одна строка `> Визуал: …`.
- Раздел **«Как собрать .pptx»** сохранён (несёт `build_presentation.py` и маркеры «Проверка:»
  — требует `test_presentation_carries_reproducible_build_procedure`).
- Служебные `##`-заголовки (например, «Как собрать .pptx») не являются слайдами и завершают
  предыдущий слайд (контракт `parse_slides`) — не вставлять контент слайдов после них.

### FR-4 — Сборка `.pptx` с новыми слайдами (BR-4)
Команда из канона (вне рантайма, dev-venv):
```bash
python3 -m venv .venv-pptx && .venv-pptx/bin/pip install python-pptx
.venv-pptx/bin/python scripts/build_presentation.py
```
Ожидаемо: печать `Собрано слайдов: N → build/orchestrator-overview.pptx`, где `N` =
фактическому числу слайдов источника (включая новые). Открытие `.pptx`: тёмная тема, светлый
текст, акцентные заголовки, корректная кириллица, новые слайды присутствуют и редактируемы.
**Это ручная проверка** (см. §6 — `python-pptx` нет в гейте тестов).

### FR-5 — Анти-дрейф нового контента (NFR-2, BR-5)
Расширить `tests/test_system_docs.py`, зафиксировав присутствие нового обязательного нарратива
в `presentation.md`:
- маркер **использования через Plane** (например, наличие подстроки уровня `plane` + признака
  оператор-инструкции, по образцу `test_presentation_covers_mandatory_narrative_bits`);
- маркер **Lite-установки** (например, `lite` / `установк`).
Точные подстроки выбирает developer; цель — чтобы случайное удаление новых слайдов рвало CI.
Все **существующие** проверки модуля остаются зелёными без послаблений.

### FR-6 — Сопровождение (BR-6)
- `CHANGELOG.md`: запись `docs:` по ORCH-105 (презентация дополнена слайдами Lite-установки и
  использования через Plane).
- Витрина: при изменении `presentation.md` норматив сопровождения ORCH-011/079 соблюдён;
  reviewer сверяет факты с golden sources.

## 4. Изменения API

**Нет.** Эндпоинты (`/queue`, `/metrics`, вебхуки и пр.) не затрагиваются.

## 5. Изменения схемы БД

**Нет.** Таблицы/миграции/индексы не вводятся и не меняются.

## 6. Требования к новым/изменённым QG checks

**Нет нового гейта.** Презентация — артефакт витрины; новый Quality Gate не регистрируется
(`QG_CHECKS` / `STAGE_TRANSITIONS` / `check_*` — байт-в-байт прежние). Контроль выполняется
**существующими** механизмами:
- `tests/test_system_docs.py` исполняется обычным тест-сьютом → попадает под `check_ci_green`
  (выход из `development`) и `check_tests_passed` (стадия `testing`).
- **Важное разграничение (честность гейта):** автоматический гейт проверяет **источник**
  (`presentation.md`: парс, нумерация, обязательные биты, процедура сборки) и инвариант
  «`python-pptx` не в прод-образе». **Сам рендер `.pptx`** в гейте **не выполняется** —
  `python-pptx` отсутствует в прод/тест-образе по канону (ORCH-011 NFR-2), сборка — вне
  рантайма в dev-venv (ручная проверка FR-4 / 04-test-plan TC-07).

## 7. Совместимость / регресс

- **Docs-only, нулевой рантайм-риск:** `src/**`, `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`,
  схема БД — байт-в-байт не тронуты; kill-switch не нужен (нет рантайм-поведения).
- **Self-hosting безопасно:** `python-pptx` не входит в прод-образ; сборка — вне рантайма;
  собранный бинарь не коммитится (`build/` в `.gitignore`).
- **Анти-дрейф сохранён:** `presentation.md` остаётся валидной для `parse_slides`; раздел
  сборки и обязательные биты — на месте; новые проверки только **добавляют** покрытие.
- **Воспроизводимая сборка:** канон ORCH-011 (источник → скрипт → `.pptx` по требованию) не
  форкается; один парсер (`parse_slides`) — один источник истины о формате.
- **Обратимость:** изменение полностью обратимо (revert правок `presentation.md` /
  `test_system_docs.py` / `CHANGELOG.md`).
- **Регресс-поверхность:** полный `pytest tests/ -q` остаётся зелёным (нет правок кода
  рантайма).
