orchestrator/docs/work-items/ORCH-105/02-trz.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

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):

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