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