--- 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` остаётся зелёным (нет правок кода рантайма).