From 3f44d5117600911f4dc62adca5e65acade0e69a1 Mon Sep 17 00:00:00 2001 From: Slava Date: Fri, 12 Jun 2026 07:39:35 +0300 Subject: [PATCH 1/8] docs: init ORCH-105 business request --- docs/work-items/ORCH-105/00-business-request.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 docs/work-items/ORCH-105/00-business-request.md diff --git a/docs/work-items/ORCH-105/00-business-request.md b/docs/work-items/ORCH-105/00-business-request.md new file mode 100644 index 0000000..278261e --- /dev/null +++ b/docs/work-items/ORCH-105/00-business-request.md @@ -0,0 +1,7 @@ +# Business Request: Подготовка презентации по орку + +Work Item ID: ORCH-105 + +## Description + +TBD -- 2.49.1 From 05d26a8f3e93eace498cd494853dddb77a07df7c Mon Sep 17 00:00:00 2001 From: claude-bot Date: Fri, 12 Jun 2026 07:49:14 +0300 Subject: [PATCH 2/8] analyst(ET): auto-commit from analyst run_id=645 --- docs/work-items/ORCH-105/01-brd.md | 169 ++++++++++++++++++ docs/work-items/ORCH-105/02-trz.md | 150 ++++++++++++++++ .../ORCH-105/03-acceptance-criteria.md | 130 ++++++++++++++ docs/work-items/ORCH-105/04-test-plan.yaml | 84 +++++++++ 4 files changed, 533 insertions(+) create mode 100644 docs/work-items/ORCH-105/01-brd.md create mode 100644 docs/work-items/ORCH-105/02-trz.md create mode 100644 docs/work-items/ORCH-105/03-acceptance-criteria.md create mode 100644 docs/work-items/ORCH-105/04-test-plan.yaml 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 -- 2.49.1 From be5e4e647f44ec04a93e92df3dc125feea54c591 Mon Sep 17 00:00:00 2001 From: claude-bot Date: Fri, 12 Jun 2026 07:55:33 +0300 Subject: [PATCH 3/8] architect(ET): auto-commit from architect run_id=646 --- ...resentation-lite-and-plane-usage-slides.md | 249 ++++++++++++++++++ docs/work-items/ORCH-105/10-tech-risks.md | 37 +++ 2 files changed, 286 insertions(+) create mode 100644 docs/work-items/ORCH-105/06-adr/ADR-001-presentation-lite-and-plane-usage-slides.md create mode 100644 docs/work-items/ORCH-105/10-tech-risks.md diff --git a/docs/work-items/ORCH-105/06-adr/ADR-001-presentation-lite-and-plane-usage-slides.md b/docs/work-items/ORCH-105/06-adr/ADR-001-presentation-lite-and-plane-usage-slides.md new file mode 100644 index 0000000..c8c21cd --- /dev/null +++ b/docs/work-items/ORCH-105/06-adr/ADR-001-presentation-lite-and-plane-usage-slides.md @@ -0,0 +1,249 @@ +--- +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 D3/D5): сборка — **вне рантайма** (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 D3/D5; 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 D3, +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 D3 и NFR-1 (`python-pptx` намеренно вне прод/тест-образа); оверинжиниринг + для контентной правки. Рендер остаётся ручным (D5). +- **Закоммитить собранный `.pptx` для удобства стейкхолдера** — отвергнуто: adr-0039 D5 / 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` (источник) diff --git a/docs/work-items/ORCH-105/10-tech-risks.md b/docs/work-items/ORCH-105/10-tech-risks.md new file mode 100644 index 0000000..ab11085 --- /dev/null +++ b/docs/work-items/ORCH-105/10-tech-risks.md @@ -0,0 +1,37 @@ +--- +work_item: ORCH-105 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-12 +model_used: claude-opus-4-8 +--- + +# 10 — Технические риски: ORCH-105 — Подготовка презентации по орку + +Work Item: **ORCH-105** · Repo: **orchestrator** · Стадия: architecture + +> Информационный (гейтом не парсится). Перечисляет риски реализации и их митигейшн. +> Решения — `06-adr/ADR-001-presentation-lite-and-plane-usage-slides.md`. + +## Реестр рисков + +| ID | Риск | Вер. | Влия. | Митигейшн | +|----|------|------|-------|-----------| +| TR-1 | **Ошибка перенумерации** при вставке слайдов в середину (пропуск/дубль номера) → падение сквозной нумерации. | Сред. | Низ. | Тест `test_presentation_source_parses_with_canonical_parser` требует `[1..N]` строго подряд → ловит мгновенно в CI; инвариант FR-3 явно выписан; ADR D2 даёт точную раскладку 19 слайдов. Откат — тривиальный revert. | +| TR-2 | **Фактдрейф**: тезис расходится с реальной возможностью / именем статуса / лейбла / скрипта (напр. «Approved выкатывает прод», «autoApprove пропускает проверки», «Lite — монолитный инсталлятор»). | Сред. | Сред. | ADR D3 — построчная привязка к golden sources (`LITE_SETUP.md`/`tech-pipeline.md`/`tech-integrations.md`/`CLAUDE.md`) с дословными именами; новый бит-тест D4 фиксирует присутствие; reviewer сверяет факты (правило агентов №6 → finding ≥ P1). | +| TR-3 | **Случайный запрещённый хост-литерал / секретоподобное значение** в тексте слайда → красный анти-дрейф. | Низ. | Низ. | Существующие `test_showcase_carries_no_forbidden_host_literals` (FORBIDDEN-импорт) и `test_showcase_carries_no_secret_like_values` (hex≥32/alnum≥40) ловят в CI; ADR D4 предписывает использовать только семантические корни/имена статусов; `8500/8501` явно безопасны (самочек эвристики). | +| TR-4 | **Хрупкий или послабляющий анти-дрейф-тест**: переобучение на целую фразу (рвётся при переформулировке) ИЛИ ослабление существующих проверок. | Сред. | Низ. | ADR D4 — ровно одна новая функция по образцу `..._mandatory_narrative_bits`, матч по семантическим корням, существующие функции байт-в-байт; пол `≥ 12` и нумерация не трогаются. | +| TR-5 | **Раздувание деки** сверх читаемого объёма (соблазн добавить >3 слайда). | Низ. | Низ. | ADR D2 ограничивает рост **+3** (deck = 19; 3-й Plane-слайд — только при переполнении лимита 6 тезисов); BRD §6 допускает ~19–20; жёсткий пол `≥ 12` не нарушается. | +| TR-6 | **Случайная правка рантайма / попадание `python-pptx` в прод-образ / коммит `.pptx`-бинаря** → нарушение self-hosting-инварианта. | Низ. | Выс. | Docs-only по ТЗ; `git diff` не должен затрагивать `src/**`/`STAGE_TRANSITIONS`/`QG_CHECKS`/схему БД (AC-7); `test_no_pptx_dependency_in_prod_image` + `build_script_toplevel_imports_are_stdlib_only` зелёные; `build/` в `.gitignore`. Скрипт сборки не правится (ADR D1). | +| TR-7 | **Ложное ощущение покрытия рендера**: рендер `.pptx` в CI не выполняется (нет `python-pptx`), визуальный дефект (битая кириллица/тема/отсутствие слайда) проходит мимо автогейта. | Сред. | Низ. | ADR D5 — честная граница: рендер проверяется **вручную** в dev-venv (FR-4/AC-5/TC-07), исход фиксирует tester; печать `Собрано слайдов: N → …` сверяется с числом слайдов источника. | + +## Сводный вывод + +Доминирующий класс — **риски точности контента** (TR-1, TR-2): чисто документарные, ловятся +существующим + одним новым структурным тестом и сверкой reviewer с golden sources; остаточный +риск низкий. Рантайм-класс (TR-6) теоретически высоковлияющий, но вероятность минимальна — +изменение docs-only по конструкции, накрыто машинными гардами витрины (AC-7) и инвариантами +adr-0039. **Эскалация `arch:major-change` не требуется; возврат в анализ не требуется.** Для +прод-конвейера (self-hosting) и для enduro-trails изменение инертно: `src/**`, стадии, гейты, +схема БД — байт-в-байт; `python-pptx` вне прод-образа; собранный бинарь не коммитится. -- 2.49.1 From 95a09b16b074096ae935d979e311f43a45ca1b63 Mon Sep 17 00:00:00 2001 From: claude-bot Date: Fri, 12 Jun 2026 07:59:45 +0300 Subject: [PATCH 4/8] architect(ET): auto-commit from architect run_id=647 --- ...001-presentation-lite-and-plane-usage-slides.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/work-items/ORCH-105/06-adr/ADR-001-presentation-lite-and-plane-usage-slides.md b/docs/work-items/ORCH-105/06-adr/ADR-001-presentation-lite-and-plane-usage-slides.md index c8c21cd..770cc81 100644 --- a/docs/work-items/ORCH-105/06-adr/ADR-001-presentation-lite-and-plane-usage-slides.md +++ b/docs/work-items/ORCH-105/06-adr/ADR-001-presentation-lite-and-plane-usage-slides.md @@ -35,9 +35,9 @@ Proposed `parse_slides` (один парсер — один источник истины о формате; её же импортирует тест-контур). - Анти-дрейф — `tests/test_system_docs.py` (валидирует структуру/нумерацию/обязательные биты нарратива/процедуру сборки; FORBIDDEN-скан + секрет-эвристика; `pptx` не в прод-образе). -- Канон **намеренно** держит инварианты (adr-0039 D3/D5): сборка — **вне рантайма** (dev-venv), - `python-pptx` **не** в прод/тест-образе, собранный `.pptx` **не коммитится** (`build/` в - `.gitignore`). +- Канон **намеренно** держит инварианты (adr-0039 §3 «Канон презентации»; детальные D4/D5 + work-item ADR-001 ORCH-011): сборка — **вне рантайма** (dev-venv), `python-pptx` **не** в + прод/тест-образе, собранный `.pptx` **не коммитится** (`build/` в `.gitignore`). **Факты для нового контента — golden sources (сверены):** @@ -86,7 +86,7 @@ QG **не** регистрируется. Рантайм (`src/**`, `STAGE_TRANS `check_*` / machine-verdict ключи — байт-в-байт. Контроль — существующими механизмами: `tests/test_system_docs.py` исполняется обычным сьютом → попадает под `check_ci_green` (выход из `development`) и `check_tests_passed` (стадия `testing`). -- **Бинарь не в git, `python-pptx` не в прод-образе** (adr-0039 D3/D5; NFR-1/NFR-3) — сохраняем. +- **Бинарь не в git, `python-pptx` не в прод-образе** (adr-0039 §3; NFR-1/NFR-3) — сохраняем. - **Локальность решения:** нет нового компонента/стадии/гейта/смены БД → сквозной `adr-NNNN` не нужен; канон уже зафиксирован adr-0039. `docs/architecture/README.md` и `internals.md` **не обновляются** (стадии/гейты/компоненты не затронуты). @@ -192,7 +192,7 @@ finding ≥ P1). Автоматический контур проверяет **источник** (`presentation.md`: парс/нумерация/обязательные биты/процедура сборки) и инвариант «`python-pptx` не в прод-образе». **Сам рендер `.pptx` в -гейте не выполняется** — `python-pptx` намеренно отсутствует в прод/тест-образе (adr-0039 D3, +гейте не выполняется** — `python-pptx` намеренно отсутствует в прод/тест-образе (adr-0039 §3, NFR-1). Сборка и визуальная проверка (тёмная тема, кириллица, новые слайды присутствуют и редактируемы) — **ручной dev-venv шаг** (FR-4 / AC-5 / тест-план TC-07). Это **сознательная честная граница**, а не пробел покрытия; tester обязан выполнить ручную сборку и зафиксировать @@ -204,9 +204,9 @@ NFR-1). Сборка и визуальная проверка (тёмная те ## Альтернативы - **Форкнуть `build_presentation.py` / завести гейт, рендерящий `.pptx` в CI** — отвергнуто: - нарушает adr-0039 D3 и NFR-1 (`python-pptx` намеренно вне прод/тест-образа); оверинжиниринг + нарушает adr-0039 §3 и NFR-1 (`python-pptx` намеренно вне прод/тест-образа); оверинжиниринг для контентной правки. Рендер остаётся ручным (D5). -- **Закоммитить собранный `.pptx` для удобства стейкхолдера** — отвергнуто: adr-0039 D5 / NFR-3 +- **Закоммитить собранный `.pptx` для удобства стейкхолдера** — отвергнуто: adr-0039 §3 / NFR-3 (бинарь не в git). Поставка = воспроизводимая сборка; готовый файл собирается командой и передаётся **вне git** (вложением к задаче Plane) — операционный шаг, не изменение кода (BRD §6). -- 2.49.1 From d016ac9b4c4f0e638ff6d645d1c5f5d4becdcf4f Mon Sep 17 00:00:00 2001 From: claude-bot Date: Fri, 12 Jun 2026 08:07:38 +0300 Subject: [PATCH 5/8] =?UTF-8?q?docs(overview):=20ORCH-105=20=E2=80=94=20?= =?UTF-8?q?=D1=81=D0=BB=D0=B0=D0=B9=D0=B4=D1=8B=20Lite-=D1=83=D1=81=D1=82?= =?UTF-8?q?=D0=B0=D0=BD=D0=BE=D0=B2=D0=BA=D0=B8=20=D0=B8=20=D0=B8=D1=81?= =?UTF-8?q?=D0=BF=D0=BE=D0=BB=D1=8C=D0=B7=D0=BE=D0=B2=D0=B0=D0=BD=D0=B8?= =?UTF-8?q?=D1=8F=20=D1=87=D0=B5=D1=80=D0=B5=D0=B7=20Plane?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Расширяю слайдо-источник презентации docs/overview/presentation.md тремя слайдами в каноне ORCH-011 (16 → 19, сквозная нумерация сохранена): - Слайд «Запуск и ведение задачи через Plane» (вход «To Analyse», статусы = индикация, наблюдение: доска + Telegram-карточка + комментарии). - Слайд «Что решает человек: гейты, авто-режим, отмена» (Approved / Confirm Deploy; autoApprove/autoDeploy/Bug — без пропуска тех. проверок; STOP). - Слайд «Lite-установка скриптами» (два контейнера платформы; только конфиг; gen_secrets.py/onboard_project.py + docker compose up -d; runbook LITE_SETUP.md; одношаговый bootstrap — это смежный Bundled, не Lite). Факты сверены с golden sources (LITE_SETUP.md, tech-pipeline.md, tech-integrations.md, CLAUDE.md). Анти-дрейф — новая функция test_presentation_covers_lite_and_plane_usage_bits в tests/test_system_docs.py (существующие проверки без послаблений). CHANGELOG обновлён. Docs+tests only: src/**/STAGE_TRANSITIONS/QG_CHECKS/check_*/схема БД — байт-в-байт; python-pptx не в прод-образе; .pptx в git не коммитится. Ручная сборка .pptx (TC-07) проверена в dev-venv: «Собрано слайдов: 19», exit 0. Refs: ORCH-105 Co-Authored-By: Claude Opus 4.8 --- CHANGELOG.md | 1 + docs/overview/presentation.md | 48 ++++++++++++++++++++++++++++------- tests/test_system_docs.py | 33 ++++++++++++++++++++++++ 3 files changed, 73 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fb01fe1..51aa89e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ Формат: [Keep a Changelog](https://keepachangelog.com/). Записи — на смысловой PR/задачу. ## [Unreleased] +- **Презентация: слайды Lite-установки и использования через Plane** (ORCH-105, `docs`): слайдо-источник `docs/overview/presentation.md` расширен тремя слайдами в каноне ORCH-011 (16 → 19, сквозная нумерация сохранена): один слайд про **Lite-установку скриптами** (два контейнера платформы — оркестратор + сторож на инфре заказчика; развёртывание без правки кода, только конфиг; помощники `gen_secrets.py`/`onboard_project.py` + `docker compose up -d`; runbook `LITE_SETUP.md` с проверкой каждого шага; одношаговый bootstrap — это смежный Bundled, не Lite) и два слайда оператор-инструкции **«как пользоваться орком через Plane»** (запуск через статус «To Analyse»; статусы Plane — индикация, не управление; оба человеческих гейта «Approved»/«Confirm Deploy»; авто-лейблы `autoApprove`/`autoDeploy`/`Bug` — снимают только человеческие решения, ни одна техническая проверка не пропускается; отмена через «STOP»; наблюдение — статусы доски + живая Telegram-карточка + комментарии со ссылками на ветку/PR). Факты сверены с golden sources (`docs/deployment/LITE_SETUP.md`, `docs/overview/tech-pipeline.md`, `tech-integrations.md`, `CLAUDE.md`). **Docs+tests only:** `src/**`/`STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/схема БД — байт-в-байт; новый QG не вводится; `python-pptx` не добавлен в прод-образ; собранный `.pptx` в git не коммитится. Анти-дрейф — новая функция `test_presentation_covers_lite_and_plane_usage_bits` в `tests/test_system_docs.py` (существующие проверки без послаблений). ADR: `docs/work-items/ORCH-105/06-adr/ADR-001-presentation-lite-and-plane-usage-slides.md` (канон витрины не меняется — `adr-0039-system-overview-docs-canon.md`). - **Витрина системы `docs/overview/`: бизнес + тех, маршруты трёх аудиторий, презентация** (ORCH-011, `docs`): единая точка входа в документацию платформы — новый docs-раздел `docs/overview/` (плоский каталог, 10 файлов, ADR-001 D1): индекс `README.md` (маршруты «Я заказчик / Я менеджер / Я разработчик» + норматив сопровождения «изменил функциональность → обнови витрину в том же PR»), бизнес-часть `business.md` (проблема → решение → что умеет фактически → ценность → 6 сценариев; без жаргона, цифры только с атрибуцией), 7 тех-блоков `tech-*.md` (архитектура со схемой потока, конвейер/гейты, агенты, модель объектов, интеграции, качество/безопасность, наблюдаемость; link-first — за деталями ссылки в golden sources, разрешённый дубль только машинно-сверяемый). **Docs+tests+dev-скрипт** (паттерн ORCH-102/103): `src/**`/`docker-compose.yml`/`Dockerfile`/`requirements*`/`STAGE_TRANSITIONS`/`QG_CHECKS`/machine-verdict/схема БД — ноль изменений. ADR: `docs/work-items/ORCH-011/06-adr/ADR-001-system-overview-canon.md`, сквозной `adr-0039-system-overview-docs-canon.md`. - **Презентация (D4/D5):** слайдо-источник `docs/overview/presentation.md` (16 слайдов в машинно-парсимой структуре «## Слайд N: …» + процедура сборки «команда + Проверка:») + dev-скрипт `scripts/build_presentation.py` (python-pptx, тёмный дизайн, редактируемый текст с точной кириллицей; чистый stdlib-парсер `parse_slides` + ленивый импорт pptx). Запуск только вне рантайма; `python-pptx` НЕ в прод-образе (машинный гард); собранный `.pptx` в git не коммитится — `build/` в `.gitignore`. - **Анти-дрейф (D6):** новый структурный `tests/test_system_docs.py` (без сети/LLM/subprocess, паттерн `test_lite_setup_doc.py`) — 10 файлов витрины; маршруты/норматив; derive-сверки с кодом: стадии импортом `src.stages.STAGE_TRANSITIONS` (вкл. `deploy-staging`/`cancelled`, порядок цепочки), exit-гейты и под-гейты именами реестра `QG_CHECKS` в нормативном порядке security → merge → coverage → image-freshness (+ маркер «не стадии»), 6 агентов glob'ом промптов, таблица эффортов class-default'ами config (ORCH-41/81); валидность относительных ссылок + обязательные golden-source ссылки; полнотекстовый FORBIDDEN-скан (импорт из `test_no_host_hardcodes.py`) + секрет-эвристика + запрет вне-репозиторных путей; слайды каноническим парсером; `pptx` отсутствует в `requirements*`/`Dockerfile`; указатели README/CLAUDE/CHANGELOG. diff --git a/docs/overview/presentation.md b/docs/overview/presentation.md index 1577fbc..09e9bef 100644 --- a/docs/overview/presentation.md +++ b/docs/overview/presentation.md @@ -67,7 +67,26 @@ > Визуал: человек с двумя кнопками и карточка задачи в телефоне -## Слайд 8: Пакетный автономный режим +## Слайд 8: Запуск и ведение задачи через Plane + +- Запуск: перевод задачи в статус «To Analyse» — единственная точка входа в конвейер +- Статусы Plane — индикация, а не управление: платформа выставляет их сама (Backlog → … → Done) +- Управляющих статусов ровно три: запуск, человеческие гейты и отмена +- Ход задачи виден сразу: статусы доски, живая карточка в Telegram, комментарии в задаче со ссылками на ветку и PR + +> Визуал: доска Plane с движущейся карточкой и зеркальное уведомление в Telegram + +## Слайд 9: Что решает человек: гейты, авто-режим, отмена + +- Гейт 1 — статус «Approved» на анализе: одобрить постановку задачи +- Гейт 2 — статус «Confirm Deploy» на деплое: подтвердить прод отдельным статусом, чтобы привычный approve не выкатил прод случайным кликом +- Лейблы «autoApprove» / «autoDeploy» снимают эти два решения для пакетного авто-режима +- Авто-режим убирает только ожидание человека — ни одна техническая проверка не пропускается +- Лейбл «Bug» — короткий багфикс-маршрут; статус «STOP» — безопасная отмена с уборкой ветки и worktree, не трогает прод + +> Визуал: две кнопки человека, переключатели авто-лейблов и стоп-кран STOP + +## Слайд 10: Пакетный автономный режим - Задачи одного проекта едут строго друг за другом — без столкновений - Каждая следующая стартует от свежего кода с результатом предыдущей @@ -76,7 +95,7 @@ > Визуал: ночная очередь задач, утром — стопка готовых -## Слайд 9: Багфикс за полцены +## Слайд 11: Багфикс за полцены - Метка «баг» — и задача едет коротким маршрутом - Пропускаются тяжёлая аналитика и отдельное проектирование @@ -85,7 +104,7 @@ > Визуал: развилка маршрутов — длинный и короткий путь к одному финишу -## Слайд 10: Самовосстановление +## Слайд 12: Самовосстановление - Упавший агент перезапускается, осиротевшая задача возвращается в очередь - Зависшие состояния находит и чинит фоновый сверщик @@ -94,7 +113,7 @@ > Визуал: платформа с автоподзаводом и внешним сторожем -## Слайд 11: Наблюдаемость +## Слайд 13: Наблюдаемость - Одна задача — одна живая карточка: стадия, агент, стоимость, время - Служебные страницы: снимок очереди и машинные метрики для мониторинга @@ -103,7 +122,7 @@ > Визуал: дашборд из карточки, очереди и графика стоимости -## Слайд 12: Одна платформа — много проектов +## Слайд 14: Одна платформа — много проектов - Несколько репозиториев из одного инстанса с общей очередью - Внутри проекта — строгий порядок, между проектами — параллельность @@ -112,7 +131,7 @@ > Визуал: один конвейер, несколько лент с разными проектами -## Слайд 13: Сценарии использования +## Слайд 15: Сценарии использования - Фича за вечер: постановка → прод с двумя кликами человека - Пакет задач на ночь: метки авто-одобрения, утром всё на проде @@ -122,7 +141,7 @@ > Визуал: пять пиктограмм-сценариев -## Слайд 14: Тираж платформы +## Слайд 16: Тираж платформы - Разворачивается на новой инфраструктуре без правки кода — только конфиг - Lite: у заказчика свои трекер и git — ставятся только оркестратор и сторож @@ -131,7 +150,18 @@ > Визуал: коробка-дистрибутив в двух размерах -## Слайд 15: Статус платформы сегодня +## Слайд 17: Lite-установка скриптами + +- Lite — два контейнера платформы: оркестратор и сторож (watchdog) на инфраструктуре заказчика +- Свои Plane, Gitea, Telegram и LLM заказчик подключает — в Lite они не входят +- Разворачивается без правки кода — только конфигом (принцип «дефолт = боевое значение») +- Скрипты-помощники: gen_secrets.py (свежие секреты), onboard_project.py (регистрация проекта: plan / apply / verify); подъём — docker compose up -d +- Маршрут — пошаговый runbook LITE_SETUP.md с проверкой каждого шага (PASS/FAIL) +- Весь стек одним комплектом и одношаговым бутстрапом — это смежный вариант Bundled, не Lite + +> Визуал: два контейнера-кубика и чек-лист шагов с галочками + +## Слайд 18: Статус платформы сегодня - В проде: автономный конвейер, мультипроектность, самовосстановление - В проде: пакетный авто-режим, багфикс-маршрут, отмена задач, журнал уроков @@ -140,7 +170,7 @@ > Визуал: чек-лист способностей с отметками «в проде» -## Слайд 16: Итог +## Слайд 19: Итог - Разработка без очередей между ролями: задача → прод за один проход - Человек принимает решения — конвейер делает работу diff --git a/tests/test_system_docs.py b/tests/test_system_docs.py index 248cd6a..a6d4f32 100644 --- a/tests/test_system_docs.py +++ b/tests/test_system_docs.py @@ -400,6 +400,39 @@ def test_presentation_covers_mandatory_narrative_bits(): assert bit in low, f"нормативный бит нарратива {bit!r} отсутствует (FR-4 / AC-7)" +def test_presentation_covers_lite_and_plane_usage_bits(): + """ORCH-105 (FR-5 / AC-4): новый обязательный контент презентации + зафиксирован анти-дрейфом — бесследное удаление слайда Lite-установки или + слайдов «как пользоваться орком через Plane» рвёт CI. Матч по lower-case + подстрокам (как `test_presentation_covers_mandatory_narrative_bits`); + маркеры — семантические корни и дословные имена статусов/лейблов (анти- + переобучение к формулировкам), все вне FORBIDDEN/секрет-эвристики.""" + low = _read("presentation.md").lower() + + # Слайд Lite-установки: корень `lite` + маркер развёртывания (FR-1 / AC-1). + assert "lite" in low, "слайд про Lite-установку отсутствует (FR-1 / AC-1)" + assert any(m in low for m in ("установк", "разверн")), ( + "слайд Lite не несёт маркера установки/развёртывания (FR-1 / AC-1)" + ) + + # Слайды использования через Plane: корень `plane` + операторские маркеры. + # Точка входа, оба человеческих гейта и отмена — дословными именами статусов + # (FR-2 / AC-2; имена сверены с tech-pipeline.md / tech-integrations.md). + assert "plane" in low, "слайды использования через Plane отсутствуют (FR-2 / AC-2)" + assert "to analyse" in low, ( + "слайды Plane-usage не называют точку входа «To Analyse» (FR-2 / AC-2)" + ) + assert "approved" in low, ( + "слайды Plane-usage не называют человеческий гейт «Approved» (FR-2 / AC-2)" + ) + assert "confirm deploy" in low, ( + "слайды Plane-usage не называют гейт прод-выкладки «Confirm Deploy» (FR-2 / AC-2)" + ) + assert "stop" in low, ( + "слайды Plane-usage не называют отмену задачи «STOP» (FR-2 / AC-2)" + ) + + def test_presentation_carries_reproducible_build_procedure(): text = _read("presentation.md") assert "build_presentation.py" in text, ( -- 2.49.1 From 95df7278e3cb6cb052dbb16bf362d110eb7c1399 Mon Sep 17 00:00:00 2001 From: claude-bot Date: Fri, 12 Jun 2026 08:12:38 +0300 Subject: [PATCH 6/8] reviewer(ET): auto-commit from reviewer run_id=649 --- docs/work-items/ORCH-105/12-review.md | 116 ++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 docs/work-items/ORCH-105/12-review.md diff --git a/docs/work-items/ORCH-105/12-review.md b/docs/work-items/ORCH-105/12-review.md new file mode 100644 index 0000000..5466cff --- /dev/null +++ b/docs/work-items/ORCH-105/12-review.md @@ -0,0 +1,116 @@ +--- +verdict: APPROVED # APPROVED | REQUEST_CHANGES — строго одно из двух, UPPERCASE +work_item: ORCH-105 +stage: review +author_agent: reviewer +status: approved +created_at: 2026-06-12 +model_used: claude-opus-4-8 +type: review +work_item_id: ORCH-105 +version: 1 +--- + +# Review ORCH-105 — Подготовка презентации по орку (слайды Lite-установки и использования через Plane) + +> Машинный вердикт читается ТОЛЬКО из `verdict:` во frontmatter. `APPROVED` → дальше по конвейеру. + +## Summary + +**Docs-only** доработка витрины: слайдо-источник `docs/overview/presentation.md` расширен **тремя** +слайдами в каноне ORCH-011 (дека 16 → 19, сквозная нумерация цела), добавлена **одна** анти-дрейф +тест-функция в `tests/test_system_docs.py`, обновлён `CHANGELOG.md`. Реализация **полностью** +соответствует ТЗ (`02-trz.md`), критериям приёмки (`03-acceptance-criteria.md`) и +`06-adr/ADR-001`. Рантайм (`src/**`, `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, схема БД) — +байт-в-байт не тронут. Факты новых слайдов сверены с golden sources. Весь +`tests/test_system_docs.py` — **зелёный (29 passed)**. P0/P1 findings нет → **APPROVED**. + +> **Замечание по среде ревью (не finding):** локальный `main` устарел (`9b7bdc0`), поэтому +> `git diff main...HEAD` ложно тянул уже смерженный контент ORCH-011. Достоверный диф снят против +> `origin/main` (`4d5e461`) — он чистый: `CHANGELOG.md`, `presentation.md`, `tests/test_system_docs.py` +> + артефакты `docs/work-items/ORCH-105/`. Никаких чужих правок в PR нет. + +## Оси проверки + +### 1. Соответствие ТЗ / Acceptance Criteria — PASS +- **FR-1 / AC-1 (Lite-слайд):** добавлен «Слайд 17: Lite-установка скриптами». Тезисы точны и + согласованы с `docs/deployment/LITE_SETUP.md`: два контейнера платформы (`orchestrator` + + `orchestrator-watchdog`), развёртывание без правки кода (только конфиг), помощники + `gen_secrets.py`/`onboard_project.py` (`plan`/`apply`/`verify`) + `docker compose up -d`, runbook + с проверкой каждого шага. **BR-5 соблюдён:** одношаговый bootstrap явно отнесён к **смежному + Bundled, не Lite** (нет «монолитного инсталлятора», нет выдуманных скриптов). +- **FR-2 / AC-2 (Plane-usage):** добавлены **два** оператор-слайда («Слайд 8: Запуск и ведение + задачи через Plane», «Слайд 9: Что решает человек: гейты, авто-режим, отмена»). Покрыты все 8 + обязательных тем: запуск «To Analyse», «индикация ≠ управление», **оба** человеческих гейта + (`Approved` на анализе и `Confirm Deploy` на деплое), авто-лейблы `autoApprove`/`autoDeploy`/`Bug`, + отмена `STOP`, наблюдение (статусы доски + Telegram-карточка + комментарии со ссылками на + ветку/PR). Имена статусов/лейблов **дословно** сверены с `tech-pipeline.md` (стр. 65/68/97) и + `tech-integrations.md` (стр. 8/13). Инвариант «авто-режим не пропускает техпроверки» зафиксирован + верно. +- **FR-3 / AC-3 (нумерация/формат):** заголовки слайдов строго сквозные `1..19`, `## Как собрать + .pptx` остаётся служебным разделом (не слайд). `test_presentation_source_parses_with_canonical_parser` + — зелёный (≥12, `[1..N]`, непустые заголовки, ≥1 тезис). +- **FR-5 / AC-4 (анти-дрейф):** добавлена `test_presentation_covers_lite_and_plane_usage_bits`, + фиксирующая `lite`+маркер установки и `plane`+`to analyse`/`approved`/`confirm deploy`/`stop`. + Существующие проверки нарратива и процедуры сборки — без послаблений, зелёные. +- **FR-6 / AC-8 (сопровождение):** запись `docs:` по ORCH-105 в `CHANGELOG.md` присутствует и + содержательна; норматив витрины ORCH-011/079 соблюдён (PR сам и есть обновление витрины). + +### 2. Соответствие ADR / инвариантам — PASS +- Реализация 1:1 c `06-adr/ADR-001`: ровно 3 слайда (2 Plane + 1 Lite), дека 16→19, **одна** новая + тест-функция, новый QG **не** регистрируется, скрипт `build_presentation.py` **не** правится + (подтверждено: вне дифа), `07/08`-доки не создаются (нет смены топологии/схемы БД). +- Канон витрины `adr-0039` не форкается; локальность решения обоснована (глобальный `adr-NNNN` не + нужен) — корректно. +- **Трассировка (TRACEABILITY):** исполняемый код с маркерами `ORCH-NNN` не затронут (docs/tests + only) → инварианты конвейера не задеты, анти-археология не срабатывает. + +### 3. Качество кода — PASS +- Новая тест-функция **содержательна** (не тривиальна): проверяет присутствие конкретных имён + статусов/лейблов, несёт docstring с привязкой к FR-5/AC-4 и предупреждением об анти-переобучении. +- Багфикс-трек (ORCH-019/BR-4) **не применим** — задача не `Bug`, регресс-тест-фиксатор не требуется. +- Маркеры теста проходят `FORBIDDEN`-скан и секрет-эвристику (весь модуль зелёный). + +### 4. Документация — PASS (см. раздел «Документация») + +### 5. Совместимость / регресс / self-hosting — PASS +- `git diff origin/main...HEAD -- 'src/**'` пуст → рантайм, стадии, гейты, схема БД не тронуты. +- `python-pptx` в прод-образ не добавлен; `build/` в `.gitignore` (стр. 19); новый `.pptx`-бинарь + не закоммичен (`docs/PRODUCT_VISION.pptx` — преэкзистент, вне дифа PR). +- Изменение полностью обратимо. + +## Findings + +### P0 — Blocker +- (нет) + +### P1 — Must fix +- (нет) + +### P2 — Should fix +- (нет) + +### P3 — Nice-to-have (не блокирует) +- Анти-дрейф `assert "stop" in low` ловит подстроку `stop`, которая встречается и в визуале + слайда 9; для большей устойчивости к точечному удалению блока STOP можно было бы матчить + `«STOP»`/`stop` в связке с маркером отмены. Решение D4 осознанно выбрало семантические корни + (анти-переобучение) — приемлемо, правка не требуется. + +## Документация + +**Обновлена корректно и в том же PR.** Этот PR сам является обновлением витрины `docs/overview/` +(презентация — артефакт витрины ORCH-011). Проверено: +- `CHANGELOG.md` — запись `docs:` по ORCH-105 присутствует. ✅ +- Витрина `docs/overview/presentation.md` — расширена; факты сверены с golden sources + (`docs/deployment/LITE_SETUP.md`, `docs/overview/tech-pipeline.md`, + `docs/overview/tech-integrations.md`, `CLAUDE.md`) — расхождений нет. ✅ +- `README.md` «Известные ограничения» (ORCH-079) — данный PR ни одного пункта не закрывает + (контентная правда о уже существующей функциональности), обновление не требуется. ✅ +- Прочие тех-блоки `docs/overview/tech-*.md`, `docs/architecture/README.md`/`internals.md` — новой + функциональности нет, обновлять нечего (правка только наполняет витрину контентом). ✅ +- `src/` не изменён → P0-условие «`src/` изменён, документация не обновлена» **не наступает**. + +**Замечание для tester:** AC-5 (ручная dev-venv сборка `.pptx`, ожидается +`Собрано слайдов: 19 → build/orchestrator-overview.pptx`, exit 0, тёмная тема/кириллица/новые +слайды) — ручной шаг стадии `testing` (TC-07), вне автоматического гейта по канону (`python-pptx` +не в тест-образе). Это сознательная честная граница (ADR D5), не пробел покрытия. -- 2.49.1 From c04dba0c0a955424d62628bafa0e8de29dd8a1c3 Mon Sep 17 00:00:00 2001 From: claude-bot Date: Fri, 12 Jun 2026 08:15:57 +0300 Subject: [PATCH 7/8] tester(ET): auto-commit from tester run_id=650 --- docs/work-items/ORCH-105/13-test-report.md | 67 ++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 docs/work-items/ORCH-105/13-test-report.md diff --git a/docs/work-items/ORCH-105/13-test-report.md b/docs/work-items/ORCH-105/13-test-report.md new file mode 100644 index 0000000..96183c4 --- /dev/null +++ b/docs/work-items/ORCH-105/13-test-report.md @@ -0,0 +1,67 @@ +--- +result: PASS # PASS | FAIL — машинный вердикт, UPPERCASE +work_item: ORCH-105 +stage: testing +author_agent: tester +status: pass +created_at: 2026-06-12 +model_used: claude-opus-4-8 +type: test-report +work_item_id: ORCH-105 +--- + +# Test Report — ORCH-105 — Подготовка презентации по орку + +> Машинный вердикт читается ТОЛЬКО из `result:` во frontmatter. `PASS` → задача переходит на +> `deploy-staging`. + +## Окружение +- Python: 3.12.13 +- pytest: 8.3.3 (plugins: cov-5.0.0, anyio-4.13.0, asyncio-0.23.8) +- Worktree (код ветки): `/repos/_wt/orchestrator/feature_ORCH-105-/` (ветка `feature/ORCH-105-`) +- Дата: 2026-06-12 + +## Smoke API (read-only) +- `GET /health` → `{"status":"ok","service":"orchestrator"}` — **OK** +- `GET /status` → активные задачи перечислены, задача ORCH-105 (id 93) в стадии `testing` — **OK** +- `GET /queue` → блок `serial_gate` присутствует (**True**), блок `auto_labels` присутствует + (**True**) — регресса смока нет — **OK** + +## Покрытие ТЗ (каждый TC из 04-test-plan.yaml ↔ 03-acceptance-criteria.md) + +| TC ID | Тип | Описание | AC | Результат | +|-------|-----|----------|----|-----------| +| TC-01 | unit | `parse_slides` разбирает `presentation.md`: слайдов 19 (≥12), номера сквозные `[1..19]`, у каждого непустой заголовок + ≥1 тезис (`test_presentation_source_parses_with_canonical_parser`) | AC-3 | PASS | +| TC-02 | unit | Обязательные биты нарратива (проблем/решени/конвейер/сценари/тираж/статус) — `test_presentation_covers_mandatory_narrative_bits` | AC-4 | PASS | +| TC-03 | unit | Новый контент зафиксирован анти-дрейфом: Lite-установка + использование через Plane — `test_presentation_covers_lite_and_plane_usage_bits` | AC-4 | PASS | +| TC-04 | unit | Процедура сборки `.pptx` цела (`build_presentation.py` + «Проверка:») — `test_presentation_carries_reproducible_build_procedure` | AC-4 | PASS | +| TC-05 | unit | Гигиена витрины: нет хост-литералов (`test_showcase_carries_no_forbidden_host_literals`) и секретоподобных значений (`test_showcase_carries_no_secret_like_values`) | AC-6 | PASS | +| TC-06 | unit | Все относительные ссылки витрины резолвятся — `test_all_relative_links_resolve_to_existing_files` | AC-6 | PASS | +| TC-07 | integration | Ручной dev-venv build: `build_presentation.py` → `Собрано слайдов: 19 → build/orchestrator-overview.pptx`, exit 0, валидный 56 КБ `.pptx` (N=19 = числу слайдов). Визуальная проверка темы/кириллицы — human-only, скрипт отработал чисто | AC-5 | PASS | +| TC-08 | unit | Self-hosting инвариант: `python-pptx` отсутствует в `requirements*`/`Dockerfile` (`test_no_pptx_dependency_in_prod_image`); top-level `build_presentation.py` stdlib-only (`test_build_script_toplevel_imports_are_stdlib_only`) | AC-7 | PASS | +| TC-09 | unit | `CHANGELOG.md` несёт запись `docs:` по ORCH-105; витрина `docs/overview/` достижима из README/CLAUDE (`test_changelog_has_orch_011_entry`, `test_repo_readme_links_overview`, `test_claude_md_carries_overview_pointer_and_normative`) | AC-8 | PASS | +| TC-10 | integration | Полный регресс `pytest tests/` зелёный — **1874 passed** | AC-8 | PASS | + +**Итог покрытия:** все 10 TC выполнены и сопоставлены с AC-1…AC-8. Дополнительно подтверждено: +- **AC-1/AC-2** (контент Lite-слайда и Plane-usage слайдов) — структурно зафиксированы TC-03 + (`test_presentation_covers_lite_and_plane_usage_bits`), фактологическая сверка — в `12-review.md` + (вердикт `APPROVED`). +- **AC-7** (docs-only): `git diff origin/main...HEAD` не содержит изменений `src/**` — + затронуты только `docs/**`, `CHANGELOG.md`, `tests/test_system_docs.py`; `build/`-артефакт + `.pptx` не закоммичен (gitignored), `python-pptx` не добавлен в прод-образ. + +## Вывод pytest + +``` +tests/test_system_docs.py ... 29 passed (включая test_presentation_covers_lite_and_plane_usage_bits) +... +================== 1874 passed, 1 warning in 74.80s (0:01:14) ================== +``` +(Единственный warning — преэкзистентный `PydanticDeprecatedSince20` в `src/config.py:8`, не +связан с ORCH-105.) + +## Итог +**PASS** — полный регресс `pytest tests/` зелёный (1874 passed), smoke read-only OK +(`serial_gate` + `auto_labels` в `/queue` присутствуют), каждый TC `04-test-plan.yaml` выполнен и +сопоставлен с критериями `03-acceptance-criteria.md`, изменение остаётся docs-only (рантайм/образ +нетронуты). Задача готова к переходу на `deploy-staging`. -- 2.49.1 From 25ce5a22a900c280843751bdedf16ffa34ea9a22 Mon Sep 17 00:00:00 2001 From: deploy-finalizer Date: Fri, 12 Jun 2026 08:25:51 +0300 Subject: [PATCH 8/8] deploy(ORCH-036): finalize SUCCESS for ORCH-105 --- docs/work-items/ORCH-105/14-deploy-log.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 docs/work-items/ORCH-105/14-deploy-log.md diff --git a/docs/work-items/ORCH-105/14-deploy-log.md b/docs/work-items/ORCH-105/14-deploy-log.md new file mode 100644 index 0000000..ea4bb7f --- /dev/null +++ b/docs/work-items/ORCH-105/14-deploy-log.md @@ -0,0 +1,12 @@ +--- +deploy_status: SUCCESS +work_item: ORCH-105 +hook_exit_code: 0 +deployed_by: deploy-finalizer +--- + +# Deploy log — ORCH-036 executable self-deploy + +Прод-деплой завершён хост-хуком с exit-code `0` -> `deploy_status: SUCCESS`. + +Вердикт зафиксирован детерминированным finalizer'ом (Фаза C), не LLM. -- 2.49.1