orchestrator/docs/work-items/ORCH-105/06-adr/ADR-001-presentation-lite-and-plane-usage-slides.md

work_item, stage, author_agent, status, created_at, model_used

work_item	stage	author_agent	status	created_at	model_used
ORCH-105	architecture	architect	proposed	2026-06-12	claude-opus-4-8

ADR-001: Расширение слайдо-источника презентации — слайд Lite-установки и слайды «как пользоваться орком через Plane»

Work Item: ORCH-105 — Подготовка презентации по орку Стадия: architecture Сквозная регистрация: N/A — локальное решение задачи. Канон витрины и презентации уже зафиксирован сквозным docs/architecture/adr/adr-0039-system-overview-docs-canon.md (ORCH-011, D3/D4/D5). ORCH-105 наполняет этот канон контентом, не меняя его инвариантов → новый глобальный adr-NNNN не вводится. Анти-археология (3+ маркеров в код-блоке) не срабатывает — правок исполняемого кода нет.

Статус

Proposed

Контекст

Заказчику нужна продуктовая презентация орка (PowerPoint) с двумя новыми смысловыми блоками: (а) выделенный слайд про Lite-установку скриптами и (б) слайды-инструкция «как пользоваться орком через Plane» (запуск, статусы, человеческие гейты, авто-лейблы, STOP, наблюдение).

Опора, не изобретать (сверено по коду/доке):

• Слайдо-источник уже существует — docs/overview/presentation.md (16 слайдов в формате ## Слайд N: Заголовок + 3–6 тезисов + опц. > Визуал:), канон ORCH-011.
• Сборка .pptx — scripts/build_presentation.py; формат парсит чистая stdlib-функция parse_slides (один парсер — один источник истины о формате; её же импортирует тест-контур).
• Анти-дрейф — tests/test_system_docs.py (валидирует структуру/нумерацию/обязательные биты нарратива/процедуру сборки; FORBIDDEN-скан + секрет-эвристика; pptx не в прод-образе).
• Канон намеренно держит инварианты (adr-0039 §3 «Канон презентации»; детальные D4/D5 work-item ADR-001 ORCH-011): сборка — вне рантайма (dev-venv), python-pptx не в прод/тест-образе, собранный .pptx не коммитится (build/ в .gitignore).

Факты для нового контента — golden sources (сверены):

• Lite — docs/deployment/LITE_SETUP.md (+ tech-pipeline.md §Тираж, adr-0037): 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 с проверкой каждого шага (PASS/FAIL). Одношаговый bootstrap (bootstrap_bundle.py) — это Bundled, не Lite.
• Plane-usage — docs/overview/tech-pipeline.md + tech-integrations.md + CLAUDE.md: вход — статус «To Analyse» (единственная точка запуска); статусы Plane = индикация, не управление (управляющих статусов ровно три); два человеческих гейта — Approved на analysis и Confirm Deploy на deploy; авто-лейблы autoApprove/autoDeploy (снимают только человеческие гейты — ни одна техническая проверка не пропускается) и Bug (багфикс-маршрут); отмена — статус STOP → cancelled (не трогает main/прод); наблюдение — статусы доски + живая карточка в Telegram + комментарии в задаче со ссылками на ветку/PR.

Почему нужно архитектурное решение, а не просто «дописать слайды»: дельта затрагивает три файла канона (presentation.md, tests/test_system_docs.py, CHANGELOG.md) и несёт реальные архитектурные развилки — рост деки за «ориентир 14–18», точная привязка каждого тезиса к golden source (риск фактдрейфа №1), форма анти-дрейфа нового контента без хрупкости и без нового гейта, и честная граница «что проверяет CI vs. что проверяется руками». Развилки зафиксированы ниже.

Решение

Сводка

ORCH-105 — docs-only расширение контента слайдо-источника внутри канона adr-0039. Добавляем ровно 3 слайда (1 Lite + 2 Plane-usage), доводя деку 16 → 19 слайдов; сохраняем сквозную нумерацию, формат, раздел сборки и тёмный дизайн. Каждый тезис привязан к golden source (D3). Анти-дрейф — одна новая тест-функция в существующем контуре (D4); новый QG не регистрируется. Рантайм (src/**, STAGE_TRANSITIONS, QG_CHECKS, check_*, схема БД) — байт-в-байт не тронут. 07-infra-requirements.md / 08-data-requirements.md — не применимы (нет смены топологии и схемы БД).

D1 — Канон не форкается; новый компонент / гейт / глобальный ADR не вводятся

Расширение целиком живёт в инвариантах adr-0039:

• Единственный источник истины о формате — parse_slides; контент пишется под него (формат слайда не меняется). Скрипт сборки не правится (парсер обобщён; правка — только при крайней необходимости, тогда сохранить ленивый импорт pptx и stdlib-only top-level).
• Новый Quality Gate НЕ регистрируется (TRZ §6): QG_CHECKS / STAGE_TRANSITIONS / check_* / machine-verdict ключи — байт-в-байт. Контроль — существующими механизмами: tests/test_system_docs.py исполняется обычным сьютом → попадает под check_ci_green (выход из development) и check_tests_passed (стадия testing).
• Бинарь не в git, python-pptx не в прод-образе (adr-0039 §3; NFR-1/NFR-3) — сохраняем.
• Локальность решения: нет нового компонента/стадии/гейта/смены БД → сквозной adr-NNNN не нужен; канон уже зафиксирован adr-0039. docs/architecture/README.md и internals.md не обновляются (стадии/гейты/компоненты не затронуты).

Привязка: BR-1, NFR-1, AC-7; TRZ §6/§7.

D2 — Структура деки и размещение (ограниченный рост, +3 → 19 слайдов)

Рост деки ограничиваем тремя слайдами (анти-раздувание; BRD §6 явно допускает ~19–20 и проходит жёсткий пол ≥ 12). Рекомендуемая раскладка (точные позиции — на усмотрение developer, жёсткое требование — только сквозная нумерация и ≥ 12):

Новый слайд	Якорь (после какого слайда)	Роль
Запуск и ведение задачи через Plane	после «Человек в контуре» (тек. №7)	оператор-инструкция: вход + статусная модель + наблюдение
Что решает человек: гейты, авто-режим, отмена	сразу за предыдущим (кластер)	оператор-инструкция: 2 гейта + авто-лейблы + STOP
Lite-установка скриптами	после «Тираж платформы» (тек. №14)	углубление обзорного слайда тиража

Итоговая нумерация (рекомендация): Plane-слайды → новые №8, №9; Lite-слайд → новый №17; всё последующее перенумеровать сквозно (deck = 19). Инвариант FR-3: вставка в середину ⇒ перенумеровать все последующие слайды; parse_slides-тест требует [1..N] строго подряд.

Разграничение с существующими слайдами (анти-дубль; для reviewer): новые Plane-слайды — процедурная оператор-инструкция («что делаете вы / что показывает платформа»), а не описание способностей. Они дополняют, не дублируют, capability-слайды «Человек в контуре» (№7), «Наблюдаемость» (тек. №11) и «Сценарии использования» (тек. №13). Lite-слайд — углубление обзорного «Тираж платформы» (тек. №14) до конкретного скрипт-маршрута.

Число Plane-слайдов = 2 (а не 3): 8 обязательных тем (запуск, статус-модель, 2 гейта, авто-лейблы, Bug, STOP, наблюдение) укладываются в 2 слайда по ≤ 6 тезисов. Если у developer тезисы перерастают лимит 6 — допустим 3-й Plane-слайд (тогда deck = 20; BRD §6 разрешает).

Привязка: BR-2/BR-3, FR-1/FR-2/FR-3, AC-1/AC-2/AC-3.

D3 — Привязка каждого тезиса к golden source (анти-фактдрейф, BR-5)

Фактдрейф — доминирующий риск (TR-2). Норматив для developer: каждый тезис нового слайда обязан выводиться из golden source ниже; запрещены выдуманные возможности, имена статусов, лейблов, скриптов.

Lite-слайд ← docs/deployment/LITE_SETUP.md (первоисточник) + tech-pipeline.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).
• Точность (FAIL-условие AC-1): НЕ называть Lite «единым монолитным инсталлятором»; одношаговый bootstrap_bundle.py — это Bundled, упоминание опционально и как смежный вариант (одной строкой, не как суть Lite).

Plane-слайд A «Запуск и ведение задачи через Plane» ← tech-integrations.md §Plane + tech-pipeline.md §Статусная модель:

• Запуск: перевод задачи в «To Analyse» — единственная точка входа в конвейер.
• Статусная модель: статусы Plane — индикация, не управление; платформа выставляет их сама; управляющих статусов ровно три (запуск, человеческие гейты, STOP).
• Наблюдение: статусы доски (Backlog → … → Done) + живая карточка в Telegram (стадия, стоимость, время, кликабельный номер задачи) + комментарии в задаче со ссылками на ветку/PR.

Plane-слайд B «Что решает человек: гейты, авто-режим, отмена» ← tech-pipeline.md §Человеческие гейты + CLAUDE.md (ORCH-089/090/019):

• Гейт 1 — Approved на analysis (одобрить постановку).
• Гейт 2 — Confirm Deploy на deploy (подтвердить прод — отдельный статус, чтобы привычный approve не выкатывал прод случайным кликом).
• Авто-лейблы autoApprove / autoDeploy — снимают только человеческие гейты; ни одна техническая проверка не пропускается (FAIL-условие AC-2 — обратное утверждение).
• Лейбл Bug — багфикс-маршрут (короче, но все гейты исполняются).
• STOP → cancelled — безопасная отмена с уборкой (рабочая ветка/worktree); не трогает main/прод-контейнер.

Точность имён критична: имена статусов/лейблов воспроизводить дословно (To Analyse/Approved/Confirm Deploy/STOP/autoApprove/autoDeploy/Bug). Reviewer сверяет факты с golden sources (BR-5; правило агентов №6 — необновлённая/расходящаяся витрина → finding ≥ P1).

Привязка: BR-5, FR-1/FR-2, AC-1/AC-2.

D4 — Анти-дрейф нового контента: одна новая тест-функция, без хрупкости, без послаблений

Решение: в tests/test_system_docs.py добавить ровно одну функцию (рекомендуемое имя test_presentation_covers_lite_and_plane_usage_bits), по образцу test_presentation_covers_mandatory_narrative_bits (lower-case подстрочный матч). Существующие функции — байт-в-байт (только добавление; NFR-2).

Требования к выбору маркеров (чтобы тест ловил удаление слайда, но не был хрупким к переформулировке):

• Lite: lite и маркер установки (установк / разверн).
• Plane-usage: plane и оператор-маркер (например to analyse / confirm deploy / stop). Точные подстроки — на усмотрение developer; выбирать семантические корни, не целые фразы (анти-переобучение).
• Матч — по lower-case тексту (как существующий бит-тест).
• Не трогать пол ≥ 12 и сквозную нумерацию в test_presentation_source_parses_with_canonical_parser — он уже покрывает счёт/формат.
• Маркеры обязаны пережить test_showcase_carries_no_forbidden_host_literals (без боевых хост-литералов) и test_showcase_carries_no_secret_like_values (без hex≥32/alnum≥40); имена статусов/лейблов и 8500/8501 этим скан-ам не противоречат.

Цель (AC-4 FAIL-условие): бесследное удаление нового слайда должно рвать CI.

Привязка: BR-5, FR-5, NFR-2, AC-4.

D5 — Честная граница гейта: источник проверяется CI, рендер .pptx — вручную

Автоматический контур проверяет источник (presentation.md: парс/нумерация/обязательные биты/процедура сборки) и инвариант «python-pptx не в прод-образе». Сам рендер .pptx в гейте не выполняется — python-pptx намеренно отсутствует в прод/тест-образе (adr-0039 §3, NFR-1). Сборка и визуальная проверка (тёмная тема, кириллица, новые слайды присутствуют и редактируемы) — ручной dev-venv шаг (FR-4 / AC-5 / тест-план TC-07). Это сознательная честная граница, а не пробел покрытия; tester обязан выполнить ручную сборку и зафиксировать исход. Ожидаемая печать: Собрано слайдов: 19 → build/orchestrator-overview.pptx (N = факт. числу слайдов), exit 0.

Привязка: BR-4, FR-4, AC-5, NFR-1.

Альтернативы

• Форкнуть build_presentation.py / завести гейт, рендерящий .pptx в CI — отвергнуто: нарушает adr-0039 §3 и NFR-1 (python-pptx намеренно вне прод/тест-образа); оверинжиниринг для контентной правки. Рендер остаётся ручным (D5).
• Закоммитить собранный .pptx для удобства стейкхолдера — отвергнуто: adr-0039 §3 / NFR-3 (бинарь не в git). Поставка = воспроизводимая сборка; готовый файл собирается командой и передаётся вне git (вложением к задаче Plane) — операционный шаг, не изменение кода (BRD §6).
• Завести сквозной adr-NNNN — отвергнуто: ничего сквозного не меняется (нет нового компонента/гейта/стадии/смены БД); канон презентации уже держит adr-0039.
• Один объединённый слайд использования — отвергнуто: AC-2 жёстко требует ≥ 2 слайда, а 8 обязательных тем переполняют лимит 6 тезисов одного слайда.
• 3+ слайда Plane по умолчанию — отвергнуто как дефолт (анти-раздувание): 2 слайда достаточны; 3-й допустим лишь при переполнении тезисов (D2).

Последствия

• + Дека получает оператор-применимый контент (Lite-маршрут + работа через Plane); каждый факт CI-заякорен к golden source новой подстрочной проверкой (D4); нулевой рантайм-риск; для enduro-trails инертно.
• + Канон не форкается: один парсер parse_slides = один источник истины; анти-дрейф только добавляет покрытие.
• − Дека растёт до 19 (выше ориентира 14–18) — принято осознанно (BRD §6), ограничено +3; митигировано плотной группировкой тезисов (D2) и порогом ≥ 12, который не нарушается.
• − Ручной рендер вне CI — принятая честная граница (D5); митигировано явным ручным шагом AC-5 / TC-07 (исход фиксирует tester).
• − (риск перенумерации) вставка в середину рвёт сквозную нумерацию при невнимательности — митигировано тестом test_presentation_source_parses_with_canonical_parser ([1..N]) и явным инвариантом FR-3 (см. TR-1).
• Применимость 07/08: 07-infra-requirements.md и 08-data-requirements.md не создаются — нет смены топологии и схемы БД (TRZ §4/§5).
• Откат: полностью обратимо — revert правок presentation.md / tests/test_system_docs.py / CHANGELOG.md (1:1, без миграций и состояния).

Ссылки

• BRD: docs/work-items/ORCH-105/01-brd.md
• TRZ: docs/work-items/ORCH-105/02-trz.md
• Acceptance: docs/work-items/ORCH-105/03-acceptance-criteria.md
• Риски: docs/work-items/ORCH-105/10-tech-risks.md
• Канон витрины/презентации (не меняется): docs/architecture/adr/adr-0039-system-overview-docs-canon.md
• Golden sources контента: docs/deployment/LITE_SETUP.md, docs/overview/tech-pipeline.md, docs/overview/tech-integrations.md, CLAUDE.md
• Сверено по коду: scripts/build_presentation.py (parse_slides), tests/test_system_docs.py (анти-дрейф витрины), docs/overview/presentation.md (источник)