---
work_item: ORCH-105
stage: architecture
author_agent: architect
status: proposed
created_at: 2026-06-12
model_used: 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` (источник)
