Compare commits

...

11 Commits

Author SHA1 Message Date
post-deploy-monitor
e4c0084d08 docs(ORCH-021): post-deploy HEALTHY/NONE for ORCH-105
All checks were successful
CI / test (push) Successful in 57s
2026-06-12 08:45:21 +03:00
deploy-finalizer
25ce5a22a9 deploy(ORCH-036): finalize SUCCESS for ORCH-105
All checks were successful
CI / test (push) Successful in 57s
2026-06-12 08:25:51 +03:00
c04dba0c0a tester(ET): auto-commit from tester run_id=650
All checks were successful
CI / test (push) Successful in 1m0s
CI / test (pull_request) Successful in 1m3s
2026-06-12 08:19:36 +03:00
95df7278e3 reviewer(ET): auto-commit from reviewer run_id=649 2026-06-12 08:19:36 +03:00
d016ac9b4c docs(overview): ORCH-105 — слайды Lite-установки и использования через Plane
Расширяю слайдо-источник презентации 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 <noreply@anthropic.com>
2026-06-12 08:19:36 +03:00
95a09b16b0 architect(ET): auto-commit from architect run_id=647 2026-06-12 08:19:36 +03:00
be5e4e647f architect(ET): auto-commit from architect run_id=646 2026-06-12 08:19:36 +03:00
05d26a8f3e analyst(ET): auto-commit from analyst run_id=645 2026-06-12 08:19:36 +03:00
3f44d51176 docs: init ORCH-105 business request 2026-06-12 08:19:36 +03:00
a8ca4db550 docs(ORCH-105): staging gate log — SUCCESS (8/10, C9a/C9b infra-waived)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-12 08:19:13 +03:00
4d5e4613e5 Merge pull request 'docs(overview): ORCH-011 — витрина системы docs/overview/ (бизнес+тех, 3 аудитории, презентация)' (#125) from feature/ORCH-011- into main
Some checks failed
CI / test (push) Has been cancelled
2026-06-11 09:42:53 +03:00
15 changed files with 1151 additions and 9 deletions

View File

@@ -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.

View File

@@ -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: Итог
- Разработка без очередей между ролями: задача → прод за один проход
- Человек принимает решения — конвейер делает работу

View File

@@ -0,0 +1,7 @@
# Business Request: Подготовка презентации по орку
Work Item ID: ORCH-105
## Description
TBD

View File

@@ -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: Заголовок` + 36 тезисов + опциональная подпись `> Визуал: …`.
- `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` с проверкой каждого шага);
- добавить **23 слайда-инструкцию «как пользоваться орком через Plane»** (запуск задачи,
статусная модель «индикация ≠ управление», два человеческих гейта — Approved и Confirm
Deploy, авто-лейблы `autoApprove`/`autoDeploy`/`Bug`, отмена STOP, наблюдение за ходом);
- при необходимости — лёгкая актуализация продуктового нарратива на текущее состояние.
- Сохранить **сквозную нумерацию слайдов с 1** (renumber при вставке в середину) и формат
(заголовок + 36 тезисов + опц. `> Визуал:`), а также раздел «Как собрать .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 (стиль)** — новые слайды держат стиль деки: 36 тезисов, опц. подпись
`> Визуал: …`, тон и терминологию `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 + 23 Plane) дека вырастает до ~1920
слайдов. Это выше «ориентира 1418» из 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` (заполняет архитектор).

View File

@@ -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) 23 слайда-инструкция **«как пользоваться орком
через Plane»**; (3) при необходимости — точечная актуализация нарратива. Сохраняем формат и
сквозную нумерацию слайдов, раздел сборки `.pptx` и тёмный дизайн. Дополняем анти-дрейф
`tests/test_system_docs.py`, чтобы новый обязательный контент был зафиксирован машинно.
Скрипт сборки `scripts/build_presentation.py` менять **не требуется** (парсер обобщённый).
Рантайм (`src/**`, стадии, гейты, БД) — **не затрагивается**.
## 2. Задействованные модули / пути
| Путь | Действие |
|------|----------|
| `docs/overview/presentation.md` | **изменить** — добавить слайд Lite + 23 слайда 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: <Заголовок>` + 36 тезисов + опц. `> Визуал:`),
точно отражающий 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)
Добавить **23** слайда оператор-инструкции, опираясь на `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))`.
- Каждый новый слайд: **непустой заголовок** + **36 тезисов** (минимум — ≥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` остаётся зелёным (нет правок кода
рантайма).

View File

@@ -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 |

View File

@@ -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

View File

@@ -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: Заголовок` + 36 тезисов + опц. `> Визуал:`), канон ORCH-011.
- Сборка `.pptx``scripts/build_presentation.py`; формат парсит **чистая stdlib-функция**
`parse_slides` (один парсер — один источник истины о формате; её же импортирует тест-контур).
- Анти-дрейф — `tests/test_system_docs.py` (валидирует структуру/нумерацию/обязательные биты
нарратива/процедуру сборки; FORBIDDEN-скан + секрет-эвристика; `pptx` не в прод-образе).
- Канон **намеренно** держит инварианты (adr-0039 §3 «Канон презентации»; детальные D4/D5
work-item ADR-001 ORCH-011): сборка — **вне рантайма** (dev-venv), `python-pptx` **не** в
прод/тест-образе, собранный `.pptx` **не коммитится** (`build/` в `.gitignore`).
**Факты для нового контента — golden sources (сверены):**
- Lite — `docs/deployment/LITE_SETUP.md` (+ `tech-pipeline.md` §Тираж, adr-0037): Lite = **два
контейнера платформы** `orchestrator` + `orchestrator-watchdog` на инфре заказчика (свои
Plane/Gitea/Telegram/LLM подключаются, в Lite не входят); разворачивается **без правки кода —
только конфиг** (принцип 10-common ORCH-101); скрипты-помощники `scripts/gen_secrets.py`
(свежие секреты) и `scripts/onboard_project.py` (`plan`/`apply`/`verify` — регистрация
проекта), подъём `docker compose up -d`; маршрут — пошаговый runbook с **проверкой каждого
шага** (PASS/FAIL). Одношаговый bootstrap (`bootstrap_bundle.py`) — это **Bundled**, не Lite.
- Plane-usage — `docs/overview/tech-pipeline.md` + `tech-integrations.md` + `CLAUDE.md`: вход —
статус **«To Analyse»** (единственная точка запуска); статусы Plane = **индикация, не
управление** (управляющих статусов ровно три); два человеческих гейта — **Approved** на
`analysis` и **Confirm Deploy** на `deploy`; авто-лейблы **autoApprove**/**autoDeploy**
(снимают только человеческие гейты — **ни одна техническая проверка не пропускается**) и
**Bug** (багфикс-маршрут); отмена — статус **STOP**`cancelled` (не трогает `main`/прод);
наблюдение — статусы доски + **живая карточка в Telegram** + комментарии в задаче со ссылками
на ветку/PR.
**Почему нужно архитектурное решение, а не просто «дописать слайды»:** дельта затрагивает три
файла канона (`presentation.md`, `tests/test_system_docs.py`, `CHANGELOG.md`) и несёт реальные
архитектурные развилки — рост деки за «ориентир 1418», точная привязка каждого тезиса к golden
source (риск фактдрейфа №1), форма анти-дрейфа нового контента без хрупкости и без нового гейта,
и честная граница «что проверяет CI vs. что проверяется руками». Развилки зафиксированы ниже.
## Решение
### Сводка
ORCH-105 — **docs-only расширение контента** слайдо-источника **внутри** канона adr-0039.
Добавляем **ровно 3 слайда** (1 Lite + 2 Plane-usage), доводя деку 16 → **19 слайдов**;
сохраняем сквозную нумерацию, формат, раздел сборки и тёмный дизайн. Каждый тезис привязан к
golden source (D3). Анти-дрейф — **одна новая тест-функция** в существующем контуре (D4); новый
QG **не** регистрируется. Рантайм (`src/**`, `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, схема
БД) — **байт-в-байт** не тронут. `07-infra-requirements.md` / `08-data-requirements.md`
**не применимы** (нет смены топологии и схемы БД).
### D1 — Канон не форкается; новый компонент / гейт / глобальный ADR не вводятся
Расширение целиком живёт в инвариантах adr-0039:
- **Единственный источник истины о формате** — `parse_slides`; контент пишется под него (формат
слайда не меняется). Скрипт сборки **не правится** (парсер обобщён; правка — только при
крайней необходимости, тогда сохранить ленивый импорт `pptx` и stdlib-only top-level).
- **Новый Quality Gate НЕ регистрируется** (TRZ §6): `QG_CHECKS` / `STAGE_TRANSITIONS` /
`check_*` / machine-verdict ключи — байт-в-байт. Контроль — существующими механизмами:
`tests/test_system_docs.py` исполняется обычным сьютом → попадает под `check_ci_green` (выход
из `development`) и `check_tests_passed` (стадия `testing`).
- **Бинарь не в git, `python-pptx` не в прод-образе** (adr-0039 §3; NFR-1/NFR-3) — сохраняем.
- **Локальность решения:** нет нового компонента/стадии/гейта/смены БД → сквозной `adr-NNNN`
не нужен; канон уже зафиксирован adr-0039. `docs/architecture/README.md` и `internals.md`
**не обновляются** (стадии/гейты/компоненты не затронуты).
**Привязка:** BR-1, NFR-1, AC-7; TRZ §6/§7.
### D2 — Структура деки и размещение (ограниченный рост, +3 → 19 слайдов)
Рост деки ограничиваем **тремя** слайдами (анти-раздувание; BRD §6 явно допускает ~1920 и
проходит жёсткий пол `≥ 12`). **Рекомендуемая раскладка** (точные позиции — на усмотрение
developer, жёсткое требование — только сквозная нумерация и ≥ 12):
| Новый слайд | Якорь (после какого слайда) | Роль |
|-------------|------------------------------|------|
| **Запуск и ведение задачи через Plane** | после «Человек в контуре» (тек. №7) | оператор-инструкция: вход + статусная модель + наблюдение |
| **Что решает человек: гейты, авто-режим, отмена** | сразу за предыдущим (кластер) | оператор-инструкция: 2 гейта + авто-лейблы + STOP |
| **Lite-установка скриптами** | после «Тираж платформы» (тек. №14) | углубление обзорного слайда тиража |
Итоговая нумерация (рекомендация): Plane-слайды → новые №8, №9; Lite-слайд → новый №17; всё
последующее перенумеровать сквозно (deck = 19). **Инвариант FR-3:** вставка в середину ⇒
перенумеровать **все** последующие слайды; `parse_slides`-тест требует `[1..N]` строго подряд.
**Разграничение с существующими слайдами (анти-дубль; для reviewer):** новые Plane-слайды —
**процедурная оператор-инструкция** («что делаете вы / что показывает платформа»), а не описание
способностей. Они дополняют, не дублируют, capability-слайды «Человек в контуре» (№7),
«Наблюдаемость» (тек. №11) и «Сценарии использования» (тек. №13). Lite-слайд — углубление
обзорного «Тираж платформы» (тек. №14) до конкретного скрипт-маршрута.
**Число Plane-слайдов = 2** (а не 3): 8 обязательных тем (запуск, статус-модель, 2 гейта,
авто-лейблы, Bug, STOP, наблюдение) укладываются в 2 слайда по ≤ 6 тезисов. Если у developer
тезисы перерастают лимит 6 — допустим 3-й Plane-слайд (тогда deck = 20; BRD §6 разрешает).
**Привязка:** BR-2/BR-3, FR-1/FR-2/FR-3, AC-1/AC-2/AC-3.
### D3 — Привязка каждого тезиса к golden source (анти-фактдрейф, BR-5)
Фактдрейф — доминирующий риск (TR-2). **Норматив для developer:** каждый тезис нового слайда
обязан выводиться из golden source ниже; **запрещены** выдуманные возможности, имена статусов,
лейблов, скриптов.
**Lite-слайд**`docs/deployment/LITE_SETUP.md` (первоисточник) + `tech-pipeline.md` §Тираж:
- Lite = **два контейнера платформы** (`orchestrator` + `orchestrator-watchdog`); свои Plane /
Gitea / Telegram / LLM подключаются (в Lite не входят).
- Разворачивается **без правки кода — только конфиг** (10-common, ORCH-101).
- Скрипты-помощники: `scripts/gen_secrets.py` (секреты), `scripts/onboard_project.py`
(`plan`/`apply`/`verify`); подъём — `docker compose up -d`.
- Маршрут — пошаговый runbook `LITE_SETUP.md` с проверкой **каждого** шага (PASS/FAIL).
- **Точность (FAIL-условие AC-1):** НЕ называть Lite «единым монолитным инсталлятором»;
одношаговый `bootstrap_bundle.py` — это **Bundled**, упоминание опционально и как **смежный**
вариант (одной строкой, не как суть Lite).
**Plane-слайд A «Запуск и ведение задачи через Plane»**`tech-integrations.md` §Plane +
`tech-pipeline.md` §Статусная модель:
- Запуск: перевод задачи в **«To Analyse»** — единственная точка входа в конвейер.
- Статусная модель: статусы Plane — **индикация, не управление**; платформа выставляет их сама;
управляющих статусов ровно **три** (запуск, человеческие гейты, STOP).
- Наблюдение: статусы доски (Backlog → … → Done) + **живая карточка в Telegram** (стадия,
стоимость, время, кликабельный номер задачи) + комментарии в задаче со ссылками на ветку/PR.
**Plane-слайд B «Что решает человек: гейты, авто-режим, отмена»**`tech-pipeline.md`
§Человеческие гейты + `CLAUDE.md` (ORCH-089/090/019):
- Гейт 1 — **Approved** на `analysis` (одобрить постановку).
- Гейт 2 — **Confirm Deploy** на `deploy` (подтвердить прод — отдельный статус, чтобы привычный
approve не выкатывал прод случайным кликом).
- Авто-лейблы **autoApprove** / **autoDeploy** — снимают **только** человеческие гейты;
**ни одна техническая проверка не пропускается** (FAIL-условие AC-2 — обратное утверждение).
- Лейбл **Bug** — багфикс-маршрут (короче, но все гейты исполняются).
- **STOP** → `cancelled` — безопасная отмена с уборкой (рабочая ветка/worktree); **не трогает**
`main`/прод-контейнер.
**Точность имён критична:** имена статусов/лейблов воспроизводить дословно
(`To Analyse`/`Approved`/`Confirm Deploy`/`STOP`/`autoApprove`/`autoDeploy`/`Bug`). Reviewer
сверяет факты с golden sources (BR-5; правило агентов №6 — необновлённая/расходящаяся витрина →
finding ≥ P1).
**Привязка:** BR-5, FR-1/FR-2, AC-1/AC-2.
### D4 — Анти-дрейф нового контента: одна новая тест-функция, без хрупкости, без послаблений
**Решение:** в `tests/test_system_docs.py` **добавить ровно одну** функцию (рекомендуемое имя
`test_presentation_covers_lite_and_plane_usage_bits`), по образцу
`test_presentation_covers_mandatory_narrative_bits` (lower-case подстрочный матч). Существующие
функции — **байт-в-байт** (только добавление; NFR-2).
Требования к выбору маркеров (чтобы тест ловил удаление слайда, но не был хрупким к
переформулировке):
- **Lite:** `lite` **и** маркер установки (`установк` / `разверн`).
- **Plane-usage:** `plane` **и** оператор-маркер (например `to analyse` / `confirm deploy` /
`stop`). Точные подстроки — на усмотрение developer; выбирать **семантические корни**, не
целые фразы (анти-переобучение).
- Матч — по lower-case тексту (как существующий бит-тест).
- **Не** трогать пол `≥ 12` и сквозную нумерацию в
`test_presentation_source_parses_with_canonical_parser` — он уже покрывает счёт/формат.
- Маркеры обязаны пережить `test_showcase_carries_no_forbidden_host_literals` (без боевых
хост-литералов) и `test_showcase_carries_no_secret_like_values` (без hex≥32/alnum≥40);
имена статусов/лейблов и `8500/8501` этим скан-ам не противоречат.
**Цель (AC-4 FAIL-условие):** бесследное удаление нового слайда должно рвать CI.
**Привязка:** BR-5, FR-5, NFR-2, AC-4.
### D5 — Честная граница гейта: источник проверяется CI, рендер `.pptx` — вручную
Автоматический контур проверяет **источник** (`presentation.md`: парс/нумерация/обязательные
биты/процедура сборки) и инвариант «`python-pptx` не в прод-образе». **Сам рендер `.pptx` в
гейте не выполняется** — `python-pptx` намеренно отсутствует в прод/тест-образе (adr-0039 §3,
NFR-1). Сборка и визуальная проверка (тёмная тема, кириллица, новые слайды присутствуют и
редактируемы) — **ручной dev-venv шаг** (FR-4 / AC-5 / тест-план TC-07). Это **сознательная
честная граница**, а не пробел покрытия; tester обязан выполнить ручную сборку и зафиксировать
исход. Ожидаемая печать: `Собрано слайдов: 19 → build/orchestrator-overview.pptx` (N = факт.
числу слайдов), exit 0.
**Привязка:** BR-4, FR-4, AC-5, NFR-1.
## Альтернативы
- **Форкнуть `build_presentation.py` / завести гейт, рендерящий `.pptx` в CI** — отвергнуто:
нарушает adr-0039 §3 и NFR-1 (`python-pptx` намеренно вне прод/тест-образа); оверинжиниринг
для контентной правки. Рендер остаётся ручным (D5).
- **Закоммитить собранный `.pptx` для удобства стейкхолдера** — отвергнуто: adr-0039 §3 / NFR-3
(бинарь не в git). Поставка = воспроизводимая сборка; готовый файл собирается командой и
передаётся **вне git** (вложением к задаче Plane) — операционный шаг, не изменение кода
(BRD §6).
- **Завести сквозной `adr-NNNN`** — отвергнуто: ничего сквозного не меняется (нет нового
компонента/гейта/стадии/смены БД); канон презентации уже держит adr-0039.
- **Один объединённый слайд использования** — отвергнуто: AC-2 жёстко требует ≥ 2 слайда, а
8 обязательных тем переполняют лимит 6 тезисов одного слайда.
- **3+ слайда Plane по умолчанию** — отвергнуто как дефолт (анти-раздувание): 2 слайда
достаточны; 3-й допустим лишь при переполнении тезисов (D2).
## Последствия
- **+** Дека получает оператор-применимый контент (Lite-маршрут + работа через Plane); каждый
факт CI-заякорен к golden source новой подстрочной проверкой (D4); нулевой рантайм-риск; для
enduro-trails инертно.
- **+** Канон не форкается: один парсер `parse_slides` = один источник истины; анти-дрейф только
**добавляет** покрытие.
- **** Дека растёт до 19 (выше ориентира 1418) — принято осознанно (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` (источник)

View File

@@ -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 допускает ~1920; жёсткий пол `≥ 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` вне прод-образа; собранный бинарь не коммитится.

View File

@@ -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), не пробел покрытия.

View File

@@ -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`.

View File

@@ -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.

View File

@@ -0,0 +1,43 @@
---
staging_status: SUCCESS
work_item: ORCH-105
stage: deploy-staging
author_agent: deployer
status: success
created_at: 2026-06-12
model_used: claude-opus-4-8
timestamp: 2026-06-12T05:18:22Z
base_url: http://localhost:8501
---
# Staging Gate Log
Staging test suite completed against the live `orchestrator-staging` instance (port 8501),
run canonically inside the container (`docker exec orchestrator-staging python3
/repos/orchestrator/scripts/staging_check.py --base-url http://localhost:8501 --mode stub`).
**Result: 8/10 checks PASS — exit code 0 → SUCCESS.**
All REAL checks green; the two failures are known sandbox-infra checks (C9a/C9b), waived
under ORCH-061 (`staging_infra_tolerance_enabled=True`). They depend on SANDBOX bot accounts
being project members, not on the pipeline.
INFRA-WAIVED: C9a Branch appears in orchestrator-sandbox, C9b Analyst job enqueued in staging queue (known sandbox-infra; real checks green)
VERDICT: SUCCESS (exit 0) — SUCCESS (infra-waived): ['C9a Branch appears in orchestrator-sandbox', 'C9b Analyst job enqueued in staging queue'] are known sandbox-infra checks; all real checks green
## Check breakdown
| Block | Check | Result |
|-------|-------|--------|
| A SMOKE | A1 GET /health → 200 status=ok | ✓ PASS |
| A SMOKE | A2 GET /queue → 200 with counts/max_concurrency/resilience | ✓ PASS |
| A SMOKE | A3 ORCH_STAGING=true (not prod) | ✓ PASS |
| B ACCESS | B4 Plane: sandbox project accessible | ✓ PASS |
| B ACCESS | B5 Gitea: orchestrator-sandbox accessible, push=true | ✓ PASS |
| B ACCESS | B6 Registry: sandbox present, prod ET/ORCH absent | ✓ PASS |
| C E2E | C7 Create issue in Plane SANDBOX | ✓ PASS |
| C E2E | C8 Trigger pipeline via /webhook/plane | ✓ PASS |
| C E2E | C9a Branch appears in orchestrator-sandbox | ✗ FAIL (INFRA-WAIVED) |
| C E2E | C9b Analyst job enqueued in staging queue | ✗ FAIL (INFRA-WAIVED) |
Staging gate passed → pipeline may advance to `deploy`.

View File

@@ -0,0 +1,14 @@
---
post_deploy_status: HEALTHY
action_taken: NONE
work_item: ORCH-105
window_s: 900
checks_total: 30
checks_failed: 0
---
# Post-deploy log — ORCH-021 post-deploy monitor
Наблюдение прода завершено: `post_deploy_status: HEALTHY`, `action_taken: NONE`.
Окно наблюдения: 900s; опросов всего: 30, из них с провалом: 0.

View File

@@ -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, (