From be5e4e647f44ec04a93e92df3dc125feea54c591 Mon Sep 17 00:00:00 2001 From: claude-bot Date: Fri, 12 Jun 2026 07:55:33 +0300 Subject: [PATCH] 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` вне прод-образа; собранный бинарь не коммитится.