diff --git a/docs/work-items/ORCH-105/01-brd.md b/docs/work-items/ORCH-105/01-brd.md new file mode 100644 index 0000000..0f22004 --- /dev/null +++ b/docs/work-items/ORCH-105/01-brd.md @@ -0,0 +1,169 @@ +--- +work_item: ORCH-105 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-12 +model_used: claude-opus-4-8 +--- + +# 01 — BRD (бизнес-требования): ORCH-105 — Подготовка презентации по орку + +Work Item: **ORCH-105** · Repo: **orchestrator** · Стадия: analysis + +## 1. Бизнес-контекст и проблема + +Заказчику нужна **презентация о продукте «Orchestrator» в формате PowerPoint** — чтобы +показывать платформу стейкхолдерам и потенциальным заказчикам. Дополнительно в презентацию +надо добавить **слайд про Lite-установку** (через скрипты-установщики) и **слайды-инструкцию +«как пользоваться орком через Plane»**. + +**Установленный факт (опора, не изобретать):** канон презентации в репозитории **уже +существует** — его ввела задача **ORCH-011** (витрина системы `docs/overview/`): + +- `docs/overview/presentation.md` — **слайдо-источник** (источник истины): 16 слайдов в + формате `## Слайд N: Заголовок` + 3–6 тезисов + опциональная подпись `> Визуал: …`. +- `scripts/build_presentation.py` — dev-скрипт сборки **редактируемого `.pptx`** в тёмном + дизайне (`python-pptx`, ленивый импорт; чистый парсер `parse_slides` — stdlib-only). +- `tests/test_system_docs.py` — анти-дрейф-контур, который машинно валидирует формат + слайдов, сквозную нумерацию, обязательные биты нарратива и процедуру сборки. + +Канон **намеренно** держит инварианты (ORCH-011 D4/D5, NFR-2): сборка идёт **вне рантайма +платформы** (одноразовый dev-venv), `python-pptx` **не входит** в прод-образ, а **собранный +`.pptx`-бинарь в git не коммитится** (`build/` в `.gitignore`). + +**Проблема (дельта ORCH-105):** текущая дека рассказывает про продукт в целом, но **не +содержит** (а) выделенного слайда о том, как просто развернуть Lite-вариант скриптами, и +(б) слайдов-инструкции для оператора «как вести задачу через Plane» (запуск, статусы, +человеческие гейты, авто-лейблы, STOP, наблюдение). Задача — **дополнить существующий +слайдо-источник** этим содержанием и убедиться, что `.pptx` собирается с новыми слайдами. +Это **docs-only** доработка контента витрины: код рантайма не меняется. + +## 2. Объём (scope) + +### В объёме +- **Расширить `docs/overview/presentation.md`:** + - добавить **один выделенный слайд про Lite-установку** (скрипт-ассистированный характер: + `gen_secrets.py` → секреты, `onboard_project.py` → регистрация проекта, `docker compose + up`, пошаговый runbook `LITE_SETUP.md` с проверкой каждого шага); + - добавить **2–3 слайда-инструкцию «как пользоваться орком через Plane»** (запуск задачи, + статусная модель «индикация ≠ управление», два человеческих гейта — Approved и Confirm + Deploy, авто-лейблы `autoApprove`/`autoDeploy`/`Bug`, отмена STOP, наблюдение за ходом); + - при необходимости — лёгкая актуализация продуктового нарратива на текущее состояние. +- Сохранить **сквозную нумерацию слайдов с 1** (renumber при вставке в середину) и формат + (заголовок + 3–6 тезисов + опц. `> Визуал:`), а также раздел «Как собрать .pptx». +- Убедиться, что `scripts/build_presentation.py` собирает валидный `.pptx`, включающий новые + слайды (скрипт менять **не требуется** — парсер обобщённый; правка только при крайней + необходимости). +- **Расширить анти-дрейф** `tests/test_system_docs.py`: зафиксировать присутствие нового + обязательного контента (Lite-установка, использование через Plane). +- Обновить `CHANGELOG.md` (запись `docs:`); при необходимости — указатель/маршрут в + `docs/overview/README.md`. + +### Вне объёма +- **Коммит собранного `.pptx`-бинаря в git** — запрещён каноном ORCH-011 D5 (`build/` + в `.gitignore`); презентация собирается по требованию. +- Добавление `python-pptx` в `requirements*`/`Dockerfile` (NFR-2; машинно запрещено тестом). +- Кастомный графический дизайн/брендинг сверх существующего тёмного текстового шаблона + (визуалы — текстовые подписи `> Визуал: …`, а не растровые картинки). +- Переписывание дизайна рендера (`build_pptx`), смена темы/шрифтов — если это не строго + необходимо. +- Любые изменения рантайма: `src/**`, `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, + схема БД — **не трогаются**. +- Переписывание `business.md` и прочих тех-блоков витрины (описанные способности — тираж и + работа через трекер — там уже отражены; ORCH-105 добавляет именно **слайды**). +- Создание отдельного монолитного «lite-инсталлятора» как нового скрипта (его нет; Lite + ставится комбинацией существующих скриптов и compose — см. §6). + +## 3. Заинтересованные стороны + +- **Заказчик / Owner** — постановщик задачи и **приёмщик** презентации; конечный + пользователь `.pptx` при показе стейкхолдерам. +- **Потенциальные заказчики / менеджеры** — аудитория презентации (нетехнический и + полу-технический читатель). +- **Операторы платформы** — целевые читатели слайдов «как пользоваться через Plane». +- **Reviewer** — контролирует норматив сопровождения витрины (изменил витрину → согласовано, + факты не разъехались с golden sources; необновлённый сопутствующий док → finding ≥ P1). + +## 4. Бизнес-требования (BR) + +- **BR-1** — Презентация о продукте в формате PowerPoint собирается из слайдо-источника + витрины и содержит связный рассказ о платформе (существующий нарратив сохранён и при + необходимости актуализирован). +- **BR-2** — В презентации есть **выделенный слайд про Lite-установку**, точно отражающий её + скрипт-ассистированный характер: секреты генерирует `scripts/gen_secrets.py`, проект + регистрирует `scripts/onboard_project.py` (`plan`/`apply`/`verify`), стек поднимается + `docker compose`, а маршрут описан пошаговым runbook `LITE_SETUP.md` с проверкой каждого + шага. Без вымышленных артефактов/скриптов. +- **BR-3** — В презентации есть **слайды-инструкция «как пользоваться орком через Plane»**, + покрывающие: запуск задачи (перевод в «To Analyse» — единственная точка входа), статусную + модель (индикация ≠ управление; управляющих статусов ровно три), **два человеческих гейта** + (Approved на `analysis`, Confirm Deploy на `deploy`), **авто-лейблы** (`autoApprove`/ + `autoDeploy`/`Bug`), **отмену STOP**, и **наблюдение за ходом** (статусы доски + живая + карточка в Telegram + комментарии в задаче). +- **BR-4** — Итоговый `.pptx` собирается документированной командой + (`scripts/build_presentation.py`) и включает **все** новые слайды; тёмный дизайн и + корректное отображение кириллицы сохранены. +- **BR-5** — Содержание презентации **фактологически точно** и согласовано с golden sources + витрины (`tech-pipeline.md`, `tech-integrations.md`, `LITE_SETUP.md`, паспорт `CLAUDE.md`): + никаких выдуманных возможностей, имён статусов, лейблов или скриптов. +- **BR-6** — Сопровождение выполнено в том же PR: `CHANGELOG.md` несёт запись `docs:` по + ORCH-105; норматив витрины (ORCH-011/079) соблюдён. + +## 5. Нефункциональные требования (NFR) + +- **NFR-1 (self-hosting безопасность)** — изменение **docs-only**: `src/**`, + `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, схема БД — байт-в-байт не трогаются; `python-pptx` + **не попадает** в прод-образ; сборка `.pptx` — только вне рантайма (dev-venv). +- **NFR-2 (анти-дрейф / совместимость формата)** — после правок `presentation.md` остаётся + валидной для канонического парсера `parse_slides` (сквозная нумерация с 1, ≥1 тезис на + слайд, непустые заголовки); **весь существующий** `tests/test_system_docs.py` — зелёный. +- **NFR-3 (бинарь не в git)** — собранный `.pptx` не коммитится; `build/` остаётся в + `.gitignore`; артефакт сборки — по требованию. +- **NFR-4 (гигиена)** — в слайдах **нет** боевых хост-литералов (FORBIDDEN-скан) и + секретоподобных значений (секрет-эвристика); относительные ссылки резолвятся. +- **NFR-5 (стиль)** — новые слайды держат стиль деки: 3–6 тезисов, опц. подпись + `> Визуал: …`, тон и терминологию `business.md` (нетехнический язык для продуктовых слайдов; + оператор-инструкция — простыми шагами). + +## 6. Допущения и ограничения + +- **Форма поставки = воспроизводимая сборка.** Deliverable — **расширенный слайдо-источник + + скрипт сборки**; сам `.pptx` производится по требованию (ORCH-011 D5). Если нетехническому + стейкхолдеру нужен готовый файл — он **собирается командой и передаётся вне git** (например, + вложением к задаче Plane); это операционный шаг, не изменение кода. Это сознательное + следование действующему машинно-проверяемому канону, а не упущение. +- **«Скрипт-установщик» для Lite** = фактические скрипты-помощники (`gen_secrets.py`, + `onboard_project.py`) + `docker compose` + verified-runbook `LITE_SETUP.md`. **Отдельного + монолитного lite-инсталлятора в репозитории нет**; одношаговый bootstrap (`bootstrap_bundle.py`) + относится к варианту **Bundled**, а не Lite. Заказчик явно просил **Lite** — слайд остаётся + точным к Lite (при желании можно одной строкой упомянуть Bundled-bootstrap как смежный + вариант, но фокус слайда — Lite). +- **Рост деки.** С добавлением ~4 слайдов (1 Lite + 2–3 Plane) дека вырастает до ~19–20 + слайдов. Это выше «ориентира 14–18» из ORCH-011 FR-4, но **проходит жёсткий тест** (`≥ 12`). + Рост оправдан явным запросом; финальное число и возможное слияние слайдов — на усмотрение + developer/architect (жёсткое требование — только сквозная нумерация и ≥ 12). +- **Сборка/проверка `.pptx`** предполагает доступность `python-pptx` в dev-venv (вне рантайма). + **Автоматический гейт тестов проверяет ИСТОЧНИК** (`presentation.md`: парс/структура/контент), + а **не отрендеренный бинарь** — рендер проверяется **вручную** в dev-venv (честное + разграничение; см. 03/04). + +## 7. Критерии успеха + +Расширенный слайдо-источник собирается в `.pptx`; слайды Lite-установки и использования через +Plane присутствуют, точны и согласованы с golden sources; сквозная нумерация и формат +сохранены; весь `tests/test_system_docs.py` (с новыми проверками) зелёный; `python-pptx` не в +прод-образе, бинарь не в git; `CHANGELOG`/витрина обновлены. Детальные PASS/FAIL — +`03-acceptance-criteria.md`. + +## 8. Риски + +- **Ошибка перенумерации** при вставке слайдов в середину → падение проверки сквозной + нумерации (`parse_slides`). +- **Дрейф фактов**: слайд расходится с реальной возможностью/именем (статус/лейбл/скрипт). +- **Случайный запрещённый литерал/секрет** в тексте слайда → красный анти-дрейф. +- **Неточная подача Lite** как монолитного инсталлятора (его нет) → вводящий в заблуждение + слайд. +- **Раздувание деки** сверх читаемого объёма. + +Краткий перечень; детальная проработка и митигации — `10-tech-risks.md` (заполняет архитектор). diff --git a/docs/work-items/ORCH-105/02-trz.md b/docs/work-items/ORCH-105/02-trz.md new file mode 100644 index 0000000..99743d5 --- /dev/null +++ b/docs/work-items/ORCH-105/02-trz.md @@ -0,0 +1,150 @@ +--- +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` остаётся зелёным (нет правок кода + рантайма). diff --git a/docs/work-items/ORCH-105/03-acceptance-criteria.md b/docs/work-items/ORCH-105/03-acceptance-criteria.md new file mode 100644 index 0000000..69ddbaf --- /dev/null +++ b/docs/work-items/ORCH-105/03-acceptance-criteria.md @@ -0,0 +1,130 @@ +--- +work_item: ORCH-105 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-12 +model_used: claude-opus-4-8 +--- + +# 03 — Критерии приёмки (Acceptance Criteria): ORCH-105 — Подготовка презентации по орку + +Work Item: **ORCH-105** · Repo: **orchestrator** · Стадия: analysis + +Формат: каждый критерий имеет **PASS** (что должно быть истинно для приёмки) и **FAIL** +(что считается провалом). Любой машинный/ручной reviewer проверяет их буквально по файлам +репозитория. + +--- + +## AC-1 — Слайд про Lite-установку присутствует и точен + +**Условие:** `docs/overview/presentation.md` содержит выделенный слайд про Lite-установку. +- **PASS:** есть слайд (блок `## Слайд N: …`), посвящённый Lite-установке, с тезисами, + отражающими: два контейнера платформы (`orchestrator` + `orchestrator-watchdog`), + развёртывание без правки кода (только конфиг), скрипты-помощники (`gen_secrets.py`, + `onboard_project.py`) и/или `docker compose`, пошаговый runbook `LITE_SETUP.md` с проверкой + шагов. Факты согласованы с `docs/deployment/LITE_SETUP.md`. +- **FAIL:** слайда нет; ИЛИ слайд называет Lite «единым монолитным инсталлятором»/упоминает + несуществующий скрипт; ИЛИ путает Lite с Bundled; ИЛИ факты расходятся с `LITE_SETUP.md`. + +--- + +## AC-2 — Слайды «как пользоваться орком через Plane» присутствуют и точны + +**Условие:** `presentation.md` содержит ≥ 2 слайда оператор-инструкции по работе через Plane. +- **PASS:** ≥ 2 слайда покрывают (суммарно): запуск задачи («To Analyse»), статусную модель + «индикация ≠ управление», **оба** человеческих гейта (Approved на `analysis` и Confirm + Deploy на `deploy`), авто-лейблы (`autoApprove`/`autoDeploy`/`Bug`), отмену **STOP**, + наблюдение за ходом (статусы доски + живая Telegram-карточка + комментарии в задаче). Имена + статусов/лейблов точны и согласованы с `tech-pipeline.md`/`tech-integrations.md`/`CLAUDE.md`. +- **FAIL:** слайдов нет или один; ИЛИ пропущен любой из двух человеческих гейтов; ИЛИ + перепутаны имена статусов/лейблов (напр. «Approved выкатывает прод»); ИЛИ утверждается, что + авто-лейблы пропускают технические проверки. + +--- + +## AC-3 — Сквозная нумерация и формат слайдов валидны + +**Условие:** канонический парсер `parse_slides` разбирает источник без нарушений. +- **PASS:** `tests/test_system_docs.py::test_presentation_source_parses_with_canonical_parser` + зелёный — слайдов ≥ 12, номера `[1..N]` строго сквозные, у каждого слайда непустой заголовок + и ≥ 1 тезис. +- **FAIL:** тест падает — пропуск/дубль в нумерации, пустой заголовок, слайд без тезисов, или + слайдов < 12. + +--- + +## AC-4 — Обязательный нарратив и процедура сборки сохранены + новые биты зафиксированы + +**Условие:** обязательные биты нарратива на месте; процедура сборки цела; новый контент +анти-дрейф-защищён. +- **PASS:** `test_presentation_covers_mandatory_narrative_bits` и + `test_presentation_carries_reproducible_build_procedure` зелёные (биты `проблем`/`решени`/ + `конвейер`/`сценари`/`тираж`/`статус` присутствуют; раздел сборки несёт `build_presentation.py` + и «Проверка»). Добавлены проверки присутствия **Lite-установки** и **использования через + Plane**, и они зелёные. +- **FAIL:** любой из этих тестов красный; ИЛИ новые биты Lite/Plane не покрыты тестом (можно + бесследно удалить новый слайд, CI не заметит). + +--- + +## AC-5 — `.pptx` собирается с новыми слайдами (ручная dev-venv проверка) + +**Условие:** документированная сборка вне рантайма даёт валидный `.pptx`, включающий новые +слайды. +- **PASS:** в dev-venv `.venv-pptx/bin/python scripts/build_presentation.py` печатает + `Собрано слайдов: N → build/orchestrator-overview.pptx` (N = числу слайдов источника, включая + новые), `exit code 0`; открытый файл показывает тёмную тему, корректную кириллицу, новые + слайды Lite/Plane — присутствуют и редактируемы. +- **FAIL:** скрипт печатает `ОШИБКА: …` / ненулевой код возврата; ИЛИ N не совпадает с числом + слайдов; ИЛИ новых слайдов нет в собранном файле; ИЛИ кириллица/тема сломаны. + +--- + +## AC-6 — Анти-дрейф и гигиена витрины зелёные + +**Условие:** структурный контур витрины проходит целиком. +- **PASS:** весь `tests/test_system_docs.py` зелёный, включая: + `test_showcase_carries_no_forbidden_host_literals` (нет боевых хост-литералов), + `test_showcase_carries_no_secret_like_values` (нет секретоподобных значений), + `test_all_relative_links_resolve_to_existing_files` (ссылки резолвятся), + `test_build_script_toplevel_imports_are_stdlib_only` (top-level скрипта без `pptx`). +- **FAIL:** любой из перечисленных тестов красный (запрещённый литерал/секрет/битая ссылка/ + `pptx` на top-level скрипта). + +--- + +## AC-7 — Self-hosting безопасность: рантайм и образ нетронуты + +**Условие:** изменение остаётся docs-only. +- **PASS:** `git diff` не содержит изменений в `src/**`, `STAGE_TRANSITIONS` (`src/stages.py`), + `QG_CHECKS`/`check_*` (`src/qg/checks.py`), схеме БД (`src/db.py`); + `test_no_pptx_dependency_in_prod_image` зелёный (`python-pptx` нет в `requirements*`/ + `Dockerfile`); собранный `.pptx` **не** добавлен в git (`build/` в `.gitignore`). +- **FAIL:** затронут любой рантайм-модуль/стадия/гейт/схема; ИЛИ `python-pptx` появился в + прод-образе; ИЛИ `.pptx`-бинарь закоммичен. + +--- + +## AC-8 — Сопровождение выполнено в том же PR + +**Условие:** доки сопровождения обновлены. +- **PASS:** `CHANGELOG.md` несёт запись `docs:` по ORCH-105; при изменении `presentation.md` + норматив витрины соблюдён; полный `pytest tests/ -q` зелёный. +- **FAIL:** нет записи в `CHANGELOG.md`; ИЛИ полный регресс `tests/` красный. + +--- + +## Сводная матрица AC ↔ FR/BR + +| AC | Покрывает | +|----|-----------| +| AC-1 | BR-2 / FR-1 | +| AC-2 | BR-3 / FR-2 | +| AC-3 | NFR-2 / FR-3 | +| AC-4 | BR-5 / FR-3 / FR-5 | +| AC-5 | BR-4 / FR-4 | +| AC-6 | NFR-4 / FR-5 | +| AC-7 | NFR-1 / NFR-3 | +| AC-8 | BR-6 / FR-6 | diff --git a/docs/work-items/ORCH-105/04-test-plan.yaml b/docs/work-items/ORCH-105/04-test-plan.yaml new file mode 100644 index 0000000..ca62476 --- /dev/null +++ b/docs/work-items/ORCH-105/04-test-plan.yaml @@ -0,0 +1,84 @@ +work_item: ORCH-105 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-12 +model_used: claude-opus-4-8 +title: "Презентация: слайды Lite-установки и использования через Plane (анти-дрейф витрины)" +framework: pytest +scope: > + Покрывается: структурная валидность слайдо-источника docs/overview/presentation.md после + добавления слайдов Lite-установки и использования через Plane (парс/нумерация/обязательные + биты/процедура сборки), фиксация нового контента анти-дрейф-тестом, гигиена витрины, + self-hosting-инварианты (python-pptx вне прод-образа, бинарь не в git), сопровождение + (CHANGELOG). Вне автоматического покрытия: фактический рендер .pptx через python-pptx — + выполняется ВНЕ рантайма в dev-venv (ORCH-011 NFR-2), поэтому TC-07 — ручной интеграционный + шаг, а не часть гейта тестов. +notes: > + Изменение docs-only: src/** не трогается, новый QG не вводится. Тесты живут в существующем + модуле tests/test_system_docs.py (ORCH-011) — большинство TC расширяют/подтверждают уже + имеющиеся проверки. Полный регресс pytest tests/ -q должен оставаться зелёным. Имена статусов + Plane и лейблов в слайдах сверяются с docs/overview/tech-pipeline.md, tech-integrations.md и + CLAUDE.md (фактологическая точность, BR-5). TC-07 (сборка .pptx) — обязательная ручная + проверка в одноразовом dev-venv: python-pptx в прод/тест-образ НЕ добавляется. + +tests: + - id: TC-01 + type: unit + description: "parse_slides разбирает presentation.md: слайдов >= 12, номера сквозные [1..N], у каждого непустой заголовок и >= 1 тезис (после добавления новых слайдов нумерация не разъехалась)." + module: tests/test_system_docs.py + expected: PASS + + - id: TC-02 + type: unit + description: "Обязательные биты нарратива присутствуют (проблем/решени/конвейер/сценари/тираж/статус) — существующая проверка остаётся зелёной после правок." + module: tests/test_system_docs.py + expected: PASS + + - id: TC-03 + type: unit + description: "Новый контент зафиксирован анти-дрейфом: добавлены и зелёные assert'ы присутствия слайда Lite-установки (напр. lite/установк) и слайдов использования через Plane (напр. plane + признак оператор-инструкции)." + module: tests/test_system_docs.py + expected: PASS + + - id: TC-04 + type: unit + description: "Процедура сборки .pptx цела: presentation.md несёт ссылку на build_presentation.py и явные маркеры «Проверка:» (test_presentation_carries_reproducible_build_procedure)." + module: tests/test_system_docs.py + expected: PASS + + - id: TC-05 + type: unit + description: "Гигиена витрины: нет боевых хост-литералов (FORBIDDEN-скан) и нет секретоподобных значений в presentation.md после добавления слайдов." + module: tests/test_system_docs.py + expected: PASS + + - id: TC-06 + type: unit + description: "Все относительные ссылки витрины (включая новые, если добавлены) резолвятся в существующие файлы (test_all_relative_links_resolve_to_existing_files)." + module: tests/test_system_docs.py + expected: PASS + + - id: TC-07 + type: integration + description: "Ручной dev-venv шаг (вне рантайма, python-pptx): .venv-pptx/bin/python scripts/build_presentation.py печатает «Собрано слайдов: N» (N = числу слайдов), exit 0; открытый .pptx — тёмная тема, кириллица корректна, новые слайды Lite/Plane присутствуют и редактируемы." + module: docs/overview/presentation.md + expected: PASS + + - id: TC-08 + type: unit + description: "Self-hosting инвариант: python-pptx отсутствует в requirements*/Dockerfile (test_no_pptx_dependency_in_prod_image); top-level scripts/build_presentation.py остаётся stdlib-only (импорт pptx ленивый)." + module: tests/test_system_docs.py + expected: PASS + + - id: TC-09 + type: unit + description: "Указатели репозитория: CHANGELOG.md несёт запись по ORCH-105 (запись docs:), витрина docs/overview/ по-прежнему достижима из README.md/CLAUDE.md." + module: tests/test_system_docs.py + expected: PASS + + - id: TC-10 + type: integration + description: "Полный регресс pytest tests/ -q зелёный — изменение docs-only, рантайм-код не тронут, регрессии нет." + module: tests/ + expected: PASS