From c455931ae7396caec1d806f4fbbd0fc59407fef9 Mon Sep 17 00:00:00 2001 From: claude-bot Date: Thu, 11 Jun 2026 09:03:56 +0300 Subject: [PATCH] architect(ET): auto-commit from architect run_id=633 --- docs/architecture/README.md | 21 + .../adr-0039-system-overview-docs-canon.md | 95 +++++ .../06-adr/ADR-001-system-overview-canon.md | 388 ++++++++++++++++++ docs/work-items/ORCH-011/10-tech-risks.md | 40 ++ 4 files changed, 544 insertions(+) create mode 100644 docs/architecture/adr/adr-0039-system-overview-docs-canon.md create mode 100644 docs/work-items/ORCH-011/06-adr/ADR-001-system-overview-canon.md create mode 100644 docs/work-items/ORCH-011/10-tech-risks.md diff --git a/docs/architecture/README.md b/docs/architecture/README.md index aaeb882..1a50dfb 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -245,6 +245,27 @@ Type B). Анти-дрейф — `tests/test_bundle_compose.py` / `test_bundled_ [adr-0038](adr/adr-0038-bundled-replication-canon.md), детально — `docs/work-items/ORCH-103/06-adr/ADR-001-bundled-stack-compose-and-bootstrap.md`. +## Витрина системы `docs/overview/` (ORCH-011 — design) + +Единая точка входа «бизнес + тех» для трёх аудиторий (заказчик / менеджер / разработчик) — +новый docs-раздел **`docs/overview/`** (семантика разделов: `overview/` — «что это за система +и как устроена», `architecture/` — инженерный справочник, `deployment/` — «как развернуть у +себя», `operations/` — «как эксплуатировать наш прод»). Состав — плоский каталог, 10 файлов: +индекс `README.md` (маршруты 3 аудиторий + норматив сопровождения), `business.md` +(бизнес-уровень без жаргона), 7 × `tech-*.md` (= 7 блоков: архитектура / конвейер / агенты / +модель объектов / интеграции / качество-безопасность / наблюдаемость), `presentation.md` +(слайдо-источник). **Link-first:** витрина ссылается на golden sources (этот README, internals, +стандарты, ADR), не форкает их; разрешённый дубль — только машинно-сверяемый тестом факт +(стадии/гейты/агенты — derive-тестами из `STAGE_TRANSITIONS`/`QG_CHECKS`/glob промптов). +**Канон презентации:** `.pptx` (тёмный дизайн) собирается из `presentation.md` dev-скриптом +`scripts/build_presentation.py` (python-pptx, запуск только вне рантайма; зависимость в +прод-образ не попадает — машинный гард); **собранный бинарь в git не коммитится**. **Норматив +сопровождения (кросс-каттинг):** «изменил функциональность → обнови витрину в том же PR»; +reviewer-ось обзорных доков (ORCH-079) расширена на витрину (finding ≥ P1). Анти-дрейф — +структурный `tests/test_system_docs.py` (паттерн `test_lite_setup_doc.py`); новый QG не +вводится, рантайм байт-в-байт. Подробнее: [adr-0039](adr/adr-0039-system-overview-docs-canon.md), +детально — `docs/work-items/ORCH-011/06-adr/ADR-001-system-overview-canon.md`. + ## Конвейер и Quality Gates ``` diff --git a/docs/architecture/adr/adr-0039-system-overview-docs-canon.md b/docs/architecture/adr/adr-0039-system-overview-docs-canon.md new file mode 100644 index 0000000..d4b350b --- /dev/null +++ b/docs/architecture/adr/adr-0039-system-overview-docs-canon.md @@ -0,0 +1,95 @@ +--- +work_item: ORCH-011 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-11 +model_used: claude-opus-4-8 +--- + +# adr-0039: Витрина системы `docs/overview/` — единая точка входа (бизнес + тех) и канон презентации (ORCH-011) + +## Статус +Proposed + +## Контекст + +Документация платформы богатая, но фрагментированная: паспорт `CLAUDE.md` (реестр доработок), +тех-витрина `README.md`, vision `docs/PRODUCT_VISION.md`, инженерный справочник +`docs/architecture/` (~1246 строк + internals), 38 сквозных ADR, стандарты, операционные и +deployment-доки. Единой точки входа «бизнес + тех» для трёх аудиторий (заказчик / менеджер / +разработчик) нет; презентацию о возможностях собирать не из чего. С тиражируемостью +(ORCH-101/102/103) появился внешний читатель. Решения Владельца: слайды PowerPoint в тёмном +дизайне; единое место — `docs/`; витрина поддерживается актуальной. + +Живые доказательства проблемы в самом репо: схема конвейера в `PRODUCT_VISION.md` §2 устарела +(нет `deploy-staging`/`cancelled`); `docs/PRODUCT_VISION.pptx` закоммичен **без пути генерации** +(невоспроизводим). Reviewer-ось обзорных доков (ORCH-079, adr-0023) по букве привязана к +`README.md` «Известные ограничения» — новую витрину не покрывает. + +Сквозной характер: вводится новый docs-раздел с нормативом сопровождения, обязательным для +**всех будущих функциональных PR**, расширяется reviewer-ось и фиксируется канон +презентационных артефактов. Детальный пакет решений (D1…D9, исходы OQ-1…OQ-5) — work-item ADR: +`docs/work-items/ORCH-011/06-adr/ADR-001-system-overview-canon.md`. + +## Решение + +1. **Новый docs-раздел `docs/overview/` — витрина системы.** Семантика разделов после ORCH-011: + `overview/` — «что это за система и как устроена» (вход для любой аудитории), `architecture/` + — инженерный справочник, `deployment/` — «как развернуть у себя», `operations/` — «как + эксплуатировать наш прод», `_standards/` — нормативы агентов. Состав — плоский каталог, + 10 файлов: индекс `README.md` (точка входа, 3 маршрута аудиторий, норматив сопровождения), + `business.md` (бизнес-уровень: проблема → решение → способности → ценность → сценарии; без + жаргона; числа только с подтверждением), 7 файлов `tech-*.md` = 7 блоков контент-карты + (архитектура / конвейер / агенты / модель объектов / интеграции / качество-безопасность / + наблюдаемость), `presentation.md` (слайдо-источник). +2. **Link-first, канон не форкается:** витрина даёт цельную картину и ссылается на golden + sources за деталями; запрещён дубль живых таблиц (компоненты, env, статусы). Разрешённый + дубль — только машинно-сверяемый тестом факт: стадии/гейты/агенты derive-тестами из + `STAGE_TRANSITIONS`/`QG_CHECKS`/glob промптов (прецедент key-sync ORCH-102). +3. **Канон презентации:** источник — `presentation.md` (машинно-парсимая слайдо-структура + `## Слайд N:` + тезисы, 14–18 слайдов); генератор — `scripts/build_presentation.py` на + python-pptx (тёмная тема, редактируемый текст, кириллица), запуск **только вне рантайма** + (dev-venv, явный запуск человеком — паттерн ORCH-009); зависимость в + `requirements*`/`Dockerfile` НЕ попадает (машинный гард в тестах). **Собранный `.pptx` в git + не коммитится** (источник истины — markdown + скрипт; существующий `PRODUCT_VISION.pptx` не + трогается, но прецедентом не является). +4. **Норматив сопровождения (кросс-каттинг):** «изменил функциональность платформы → обнови + витрину `docs/overview/` в том же PR» — в индексе витрины и `CLAUDE.md` (правило агентов №2); + **reviewer-ось обзорных доков ORCH-079 расширяется** точечной врезкой в + `.openclaw/agents/reviewer.md`: функциональность из витрины изменена, витрина не обновлена → + finding ≥ P1 (расширение трактовки той же оси; канон 52d и verdict-ключи — байт-в-байт; + анти-регресс `test_agent_prompts_canon.py`). +5. **Анти-дрейф — `tests/test_system_docs.py`** (структурный, без сети/LLM/subprocess, паттерн + `test_lite_setup_doc.py`): наличие/непустота 10 файлов; маршруты и норматив в индексе; + сверка стадий и имён гейтов импортом из кода; полнота 6 агентов glob'ом промптов; валидность + относительных ссылок; полнотекстовый FORBIDDEN-скан (импорт из `test_no_host_hardcodes.py`) + + секрет-эвристика; парс слайдо-источника функцией самого генератора; чистота + `requirements*`/`Dockerfile` от pptx; указатели README/CLAUDE/CHANGELOG. Новый QG НЕ + регистрируется — тесты исполняются существующими гейтами. + +Рантайм байт-в-байт: `src/**`, compose, Dockerfile, `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/ +machine-verdict/схема БД — не тронуты; kill-switch не нужен (доки и dev-скрипт конвейером не +исполняются). + +## Последствия + +- **+** Закрывается корневая фрагментация: одна точка входа для трёх аудиторий; презентация + собирается за одну команду из версионируемого источника; машинно-проверяемые факты витрины — + CI-гарантии. +- **+** Нулевой риск рантайма; для enduro-trails инертно. +- **−** Новый golden source = обязанность каждого функционального PR (в этом смысл задачи); + митигировано link-first + derive-тестами + reviewer-осью. +- **−** Точечная правка промпта reviewer — поверхность канона 52d; держится анти-регресс + тестами. +- **Откат:** удалить `docs/overview/`, тест-модуль, скрипт, вернуть точечные правки указателей + и промпта — 1:1, без миграций и состояния. + +## Ссылки + +- Детально: `docs/work-items/ORCH-011/06-adr/ADR-001-system-overview-canon.md` (D1…D9), + `docs/work-items/ORCH-011/10-tech-risks.md` +- BRD/TRZ/AC: `docs/work-items/ORCH-011/01-brd.md` / `02-trz.md` / `03-acceptance-criteria.md` +- Соседние каноны: adr-0019 (стандарт доков), adr-0021 (канон промптов 52d), adr-0023 + (ось обзорных доков ORCH-079 — расширяется), adr-0029 (порядок под-гейтов), adr-0037/0038 + (deployment-каноны) diff --git a/docs/work-items/ORCH-011/06-adr/ADR-001-system-overview-canon.md b/docs/work-items/ORCH-011/06-adr/ADR-001-system-overview-canon.md new file mode 100644 index 0000000..b04acb7 --- /dev/null +++ b/docs/work-items/ORCH-011/06-adr/ADR-001-system-overview-canon.md @@ -0,0 +1,388 @@ +--- +work_item: ORCH-011 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-11 +model_used: claude-opus-4-8 +--- + +# ADR-001: Витрина системы `docs/overview/` — структура, путь к PPTX, анти-дрейф контур + +Work Item: **ORCH-011** — Полная документация системы мультиагентов оркестратора (бизнес + тех, для людей и презентаций) +Стадия: **architecture** +Сквозная регистрация: **`docs/architecture/adr/adr-0039-system-overview-docs-canon.md`** +(новый docs-раздел `docs/overview/` с нормативом сопровождения, обязательным для всех будущих +функциональных PR, + расширение reviewer-оси обзорных доков ORCH-079 — кросс-каттинг). + +## Статус +Proposed + +## Контекст + +Решения Владельца (BRD §1.4): D-1 презентация = PowerPoint, тёмный дизайн, точный рендеринг; +D-2 три аудитории (разработчики/заказчики/менеджеры); D-3 единое место — `docs/` репозитория; +D-4 витрина поддерживается актуальной сразу после изменения функционала. + +Факты, сверенные с кодом/репо на ветке задачи: + +- **Документация богатая, но фрагментированная** (BRD §1.2, проверено): паспорт `CLAUDE.md` + (реестр доработок, не вводный текст), тех-витрина `README.md`, vision + `docs/PRODUCT_VISION.md` (v1.0, «концепция развития»), инженерный справочник + `docs/architecture/README.md` (~1246 строк) + `internals.md`, 38 сквозных ADR, стандарты + `docs/_standards/`, операционные/деплойные доки. Единой точки входа «бизнес + тех» нет. +- **Живое доказательство риска гниения (R-1):** схема конвейера в `docs/PRODUCT_VISION.md` §2 + уже устарела — в ней нет стадии `deploy-staging` и стока `cancelled`, фактически + присутствующих в `src/stages.py::STAGE_TRANSITIONS` (9 ключей + `cancelled`). Снапшот без + машинной сверки расходится с кодом за недели. +- **Прецедент бинаря без воспроизводимости:** `docs/PRODUCT_VISION.pptx` закоммичен, но пути + его генерации в репо нет (`grep pptx scripts/ docs/` — пусто) — ровно тот паттерн + «невоспроизводимый артефакт», который BR-5 требует исключить. +- **Reviewer-ось обзорных доков (ORCH-079) по букве привязана к README:** + `.openclaw/agents/reviewer.md` формулирует ось через «пункт из `README.md` „Известные + ограничения“»; новая витрина под букву оси не подпадает (релевантно OQ-5). История ORCH-079 + показывает: общего правила «документация = golden source» недостаточно — обзорные доки гниют, + пока ось не названа явно. +- **Тестовая механика готова:** паттерны структурных доков-тестов — + `tests/test_lite_setup_doc.py` / `test_bundled_setup_doc.py` (разделы по порядку, кирпичи, + скан FORBIDDEN импортом из `tests/test_no_host_hardcodes.py` (`FORBIDDEN`, + `find_violations`), секрет-эвристика, кросс-рефы); импорт `STAGE_TRANSITIONS` в тестах — + норма (ORCH-091: полнота derive из кода, не статичный список); импорт `QG_CHECKS` — + `tests/test_qg_registry_snapshot.py`; импорт чистых функций из `scripts/` — + `tests/test_bootstrap_script.py`. +- **Источники контента самодостаточны внутри репо** (BRD §6): вне-репозиторные затравки + (`tasks/…`, `memory/…`) недоступны и не нужны; таблица модель/эффорт — ORCH-41/81 + (developer=`xhigh`, tester/deployer=`medium`, прочие=`high`, все на `claude-opus-4-8`). +- `docs/overview/` свободен (коллизий имён нет). + +Задача — **docs+tests (+dev-скрипт)** (паттерн ORCH-102/103): `src/**`, +`docker-compose.yml`, `Dockerfile`, `requirements*` читаются как источник истины и НЕ меняются; +конвейер (`STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict/схема БД) — байт-в-байт. +Kill-switch не нужен: документация и dev-скрипт конвейером не исполняются (активация генерации — +только явный запуск человеком, паттерн ORCH-009). + +## Решение + +### Сводка + +Создаётся новый docs-раздел **`docs/overview/`** — витрина системы: индекс `README.md` +(точка входа, маршруты трёх аудиторий, норматив сопровождения), бизнес-часть `business.md`, +семь тех-файлов `tech-*.md` (= 7 блоков контент-карты TRZ FR-3, link-first), слайдо-источник +`presentation.md` + dev-скрипт `scripts/build_presentation.py` (python-pptx, вне прод-образа; +бинарь `.pptx` НЕ коммитится — D5). Машинно-проверяемые факты витрины (стадии, гейты, агенты, +ссылки, гигиена секретов, слайдо-структура, чистота prod-зависимостей) защищаются структурным +`tests/test_system_docs.py` (D6). Reviewer-ось обзорных доков точечно расширяется на витрину +(D7). Исходы всех открытых вопросов ТЗ §9 (OQ-1…OQ-5) — в D1/D4/D5/D9/D7 соответственно. + +### D1 (исход OQ-1) — Размещение и состав: `docs/overview/`, плоский каталог, 10 файлов + +**Решение: каталог `docs/overview/`** (рекомендация аналитика подтверждена). Семантика +docs-разделов после ORCH-011: `overview/` — «что это за система и как она устроена» (читатель — +любой из трёх аудиторий, входит впервые); `architecture/` — инженерный справочник (детали); +`deployment/` — «как развернуть у себя» (ORCH-102/103); `operations/` — «как эксплуатировать +наш прод»; `_standards/` — нормативы для агентов. + +**Состав — плоский каталог, 10 файлов** (модульность NFR-6: будущие правки точечные; плоскость — +одна глубина относительных ссылок и простые globs в тестах; индекс — `README.md`, а не +`index.md`: авто-рендер в web-UI Gitea, симметрия `docs/architecture/README.md`): + +| Файл | Содержание | Покрывает | +|------|-----------|-----------| +| `README.md` | индекс: «что это» в 1–2 абзацах; навигация на все части; 3 маршрута аудиторий (D8); норматив сопровождения (D8) | FR-1, FR-5, FR-6, AC-1, AC-8, AC-9 | +| `business.md` | бизнес-уровень (D2) | FR-2, AC-2 | +| `tech-architecture.md` | блок 1: компоненты и связи + диаграмма потока | FR-3.1, AC-3 | +| `tech-pipeline.md` | блок 2: конвейер/стадии/гейты/под-гейты/откаты/человеческие гейты/авто-лейблы/багфикс-трек/serial gate/статусная модель Plane | FR-3.2, AC-4 | +| `tech-agents.md` | блок 3: 6 ролей, входы/выходы/артефакты/verdict-ключи, таблица модель/эффорт, канон промптов | FR-3.3, AC-5 | +| `tech-data-model.md` | блок 4: Project → Work-Item/Task → Jobs → Agent-runs → события/дедуп → вспомогательные таблицы; словарь терминов | FR-3.4 | +| `tech-integrations.md` | блок 5: Plane / Gitea / LLM / Telegram | FR-3.5 | +| `tech-quality-security.md` | блок 6: философия QG, frontmatter-контракт, security/coverage-гейты, канон секретов, self-hosting-страховки | FR-3.6 | +| `tech-observability.md` | блок 7: live-карточка, `/queue`, `/metrics`, sidecar, журнал уроков, стоимость | FR-3.7 | +| `presentation.md` | слайдо-источник + процедура сборки `.pptx` (D4) | FR-4, AC-7 | + +Один тех-блок = один файл (а не монолит `tech.md` и не два файла «business/tech»): блоки +независимы по темпу устаревания (pipeline меняется чаще, чем интеграции), точечный PR правит +один файл; тесту проще ассертить присутствие и непустоту каждого блока пофайлово. + +Привязка: BR-1, NFR-6, AC-1, AC-3. + +### D2 — Бизнес-уровень: текущее состояние, не vision; числа только с подтверждением + +**Решение: `business.md` описывает фактическое состояние платформы** (контент-минимум FR-2: +проблема → решение → что умеет → ценность → ≥5 сценариев), переиспользуя нарратив +`docs/PRODUCT_VISION.md` §1–2 со сверкой с кодом. Нормативные правила: + +- **Разделение ролей документов:** PRODUCT_VISION остаётся vision («куда идём», не трогается; + допустима врезка-ссылка на витрину — на усмотрение developer); `business.md` — «что есть + сейчас». Расхождение vision ↔ код (пример: устаревшая схема конвейера в vision §2) в витрину + не переносится — витрина строится от `STAGE_TRANSITIONS`. +- **Числовые метрики** (скорость/стоимость) — только с внутрирепозиторным подтверждением либо + с явной атрибуцией «оценка из PRODUCT_VISION»; новые цифры не изобретать (FR-2, AC-12). +- **Без жаргона:** кодовые идентификаторы (`ORCH-NNN`, имена функций/модулей) в основном тексте + не используются; термины конвейера (стадия, гейт, ревью) объясняются по-человечески; детали — + сносками/ссылками в тех-часть (AC-2). +- Обязательный минимум способностей — список AC-2 (конвейер задача→прод, мультипроектность, + самовосстановление, пакетный авто-режим, багфикс-трек, STOP, наблюдаемость, self-hosting, + тираж Lite/Bundled) — каждый пункт сводится к одному абзацу простым языком. + +Привязка: BR-2, FR-2, AC-2, AC-12. + +### D3 — Тех-уровень: 7 файлов по контент-карте TRZ, link-first, согласованность с кодом + +**Решение: контент-карта TRZ §3 FR-3 принимается как нормативная** (обязательное содержание и +источники истины каждого блока — таблица FR-3, в ADR не дублируется). Архитектурные уточнения: + +- **Link-first (BR-4, анти-«вторая правда»):** каждый файл даёт цельную картину уровня + «понять устройство» и ведёт ссылкой в golden source за деталями + (`docs/architecture/README.md`, `internals.md`, `_standards/*`, ADR-реестр, deployment-доки). + Запрещено копировать в витрину таблицы/списки, которые живут в golden source и меняются с + кодом (таблица компонентов, карта env, 22 статуса Plane). Разрешённый дубль — только + машинно-сверяемый тестом факт (перечень стадий, имена гейтов, 6 агентов, таблица + модель/эффорт) — ровно потому, что тест D6 рвёт CI при дрейфе (прецедент — key-sync TC-02b + ORCH-102). +- **`tech-architecture.md` несёт одну диаграмму потока** «вебхук → очередь → агент → гейт → + переход» (mermaid или ASCII — на выбор developer; AC-3 требует хотя бы одну). +- **`tech-pipeline.md`:** схема стадий включает `deploy-staging` и сток `cancelled`; под-гейты + ребра `deploy-staging→deploy` перечисляются в фактическом порядке **security → merge → + coverage → image-freshness** (нормативный порядок — adr-0029/ORCH-027) и явно помечаются как + **врезки в переход, а не стадии** (AC-4); под-гейт `deploy→done` (merge-verify) — аналогично; + человеческие гейты (Approved, Confirm Deploy) и их снятие авто-лейблами (ORCH-089), STOP + (ORCH-090), багфикс-маршрут (ORCH-019), serial gate/freeze (ORCH-088); «статусы Plane = + индикация ≠ управление» (ORCH-066). +- **`tech-agents.md`:** паспорт каждой из 6 ролей по `PIPELINE_DOCS.md` §2 (назначение, стадия, + вход, артефакты, machine-verdict ключ — имена байт-в-байт: `verdict:`/`result:`/ + `staging_status:`/`deploy_status:`/`security_status:`); таблица модель/эффорт = фактический + резолв config (ORCH-41/74/81). +- **Терминология** едина со статусной моделью Plane (ORCH-066) и PIPELINE_DOCS (NFR-4); язык — + русский. + +Привязка: BR-3, BR-4, FR-3, AC-3…AC-6. + +### D4 (исход OQ-2) — Презентация: `presentation.md` (машинно-парсимый источник) + `scripts/build_presentation.py` на python-pptx + +**Решение: слайдо-источник — `docs/overview/presentation.md`** с жёсткой машинно-парсимой +структурой: + +```markdown +## Слайд N: <Заголовок> +- <тезис 1> (3–6 тезисов на слайд) +- <тезис 2> +> Визуал: <подпись визуального мотива слайда> (опционально) +``` + +Нумерация сквозная с 1; объём — **14–18 слайдов** (в коридоре ориентира FR-4 12–20); +нормативные смысловые биты нарратива (порядок FR-4): проблема → решение → как работает +(конвейер+гейты) → роли агентов → человек в контуре → возможности (автономный пакетный режим, +багфикс-трек, самовосстановление, наблюдаемость) → сценарии → тираж → статус платформы. +Точная нарезка по слайдам — за developer; тест D6 ассертит структуру и биты, не прозу. + +**Генератор — `scripts/build_presentation.py` на `python-pptx`:** + +- **Запуск только вне рантайма** (host/dev venv, явный запуск человеком — паттерн ORCH-009); + `python-pptx` НЕ добавляется в `requirements*`/`Dockerfile` (NFR-2; машинный гард — D6 TC-09). +- **Архитектура скрипта:** чистая функция-парсер `parse_slides(text) -> list[Slide]` + (stdlib-only, без импорта pptx) + рендерер с **ленивым** `import pptx` внутри функции сборки. + Один парсер = один источник истины о формате: `tests/test_system_docs.py` импортирует + `parse_slides` (механика импорта из `scripts/` — прецедент `test_bootstrap_script.py`) и + валидирует слайдо-источник без установленного python-pptx. +- **Тёмный дизайн (D-1):** константы темы в скрипте — тёмный фон (≈`#1F1F2E`), светлый текст, + один акцентный цвет; шрифты — стандартные системные с полной кириллицей (Calibri/Arial). + python-pptx пишет **настоящий редактируемый текст** в slide-объекты → «точный рендеринг» + гарантирован самим PowerPoint (а не headless-браузером), кириллица не растрируется, Владелец + может править слайды руками. +- **Процедура — в `presentation.md`**, раздел «Как собрать .pptx», форма «fenced-команда + + Проверка:» (канон LITE_SETUP): создать venv → `pip install python-pptx` → запуск скрипта → + проверка (скрипт печатает число собранных слайдов; файл открывается, тема тёмная). Дефолтный + выход — `build/orchestrator-overview.pptx` (D5). + +**Почему python-pptx, а не альтернативы:** Marp → pptx требует Node+Chromium и экспортирует +слайды растровыми картинками (нередактируемо, текст не выделяется — против «точного +рендеринга» как редактируемого артефакта); pandoc → pptx ограниченно управляет тёмной темой +(reference-doc с мастер-слайдами — отдельный бинарный артефакт в репо); «только ручная +процедура» — слабейшая воспроизводимость (человек = источник дрейфа). python-pptx: один +pip-пакет в одноразовом dev-venv, детерминированный код-как-дизайн, тестируемый парсер. + +Привязка: BR-5, FR-4, AC-7, NFR-2. + +### D5 (исход OQ-3) — Бинарь `.pptx` НЕ коммитится; источник истины — markdown + скрипт + +**Решение: собранный `.pptx` в git НЕ коммитится.** Канон: источник истины — +`presentation.md` + `build_presentation.py`; артефакт собирается по требованию за одну команду. +Обоснование: бинарь не диффуем, анти-дрейф тесты его содержимое не проверяют → закоммиченный +deck молча устаревает относительно источника (живой пример — `docs/PRODUCT_VISION.pptx`: +закоммичен, пути генерации нет, контент vision уже разошёлся с кодом); BR-5 требует +воспроизводимость пути, не бинарь (BRD §6). + +- Дефолтный выход генератора — `build/orchestrator-overview.pptx`; в `.gitignore` добавляется + строка `build/` (разрешённое отклонение диффа, не рантайм). +- **Существующий `docs/PRODUCT_VISION.pptx` не трогается** (артефакт другого work item; + ретроактивная чистка — вне объёма §2.2). Новый канон действует на витрину и вперёд. + +Привязка: BR-5, AC-7, BRD §6. + +### D6 (FR-7) — Анти-дрейф контур: `tests/test_system_docs.py` + +**Решение: один структурный модуль, детерминированный, без сети/LLM/subprocess** (образец — +`test_lite_setup_doc.py`/`test_bundled_setup_doc.py`). Нормативные семейства проверок (точная +нарезка по тест-функциям — за developer, `04-test-plan.yaml` дополняется на development): + +| TC | Проверка | Механика | +|----|----------|----------| +| TC-01 | Все 10 файлов витрины D1 существуют и непусты | `Path.exists()` + размер | +| TC-02 | Индекс: 3 маршрута аудиторий («Я заказчик» / «Я менеджер» / «Я разработчик») и норматив сопровождения присутствуют; из индекса по относительным ссылкам достижимы business / все 7 tech / presentation (AC-1) | regex-извлечение ссылок + подстроки | +| TC-03 | **Карта стадий = код:** каждый ключ `src.stages.STAGE_TRANSITIONS` (вкл. `deploy-staging`, `cancelled`) упомянут в `tech-pipeline.md`; порядок основной цепочки created→…→done — по возрастанию позиций вхождений; derive из импорта, не статичный список (паттерн ORCH-091) | `import src.stages` + поиск позиций | +| TC-04 | **Гейты = код:** имя exit-гейта каждого ребра (`qg` из `STAGE_TRANSITIONS`) упомянуто в `tech-pipeline.md`; под-гейты названы фактическими именами реестра `QG_CHECKS` (`check_security_gate`, `check_branch_mergeable`, `check_coverage_gate`, `check_staging_image_fresh`) и идут в нормативном порядке security → merge → coverage → image-freshness (порядок — фикс adr-0029, позиционный ассерт); рядом с под-гейтами есть маркер «не стадии» (врезки) | импорт `STAGE_TRANSITIONS` + `QG_CHECKS`, позиции подстрок | +| TC-05 | **Полнота 6 агентов:** derive из glob `.openclaw/agents/*.md` (не статичный список) — стем каждого файла упомянут в `tech-agents.md`; таблица эффортов сходится с config-дефолтами (поля class-default `agent_effort_`, ORCH-81) | glob + `import src.config` | +| TC-06 | **Валидность ссылок:** все относительные md-ссылки всех файлов витрины резолвятся в существующие файлы; обязательный список ссылок AC-6 (architecture/README, internals, PIPELINE_DOCS, HANDOFF_PROTOCOL, adr-реестр, LITE_SETUP, BUNDLED_SETUP, PRODUCT_VISION, CLAUDE.md) присутствует | regex `\[..\]\((..)\)` + `Path.exists()` относительно файла | +| TC-07 | **Гигиена:** полнотекстовый скан всех 10 файлов витрины — нет литералов центрального списка `FORBIDDEN` (импорт из `tests/test_no_host_hardcodes.py`, не копия) и секретоподобных значений (эвристика hex/base64 ≥ 32 симв., не плейсхолдер); нет ссылок на вне-репозиторные пути (`tasks/`, `memory/`) (AC-12) | `find_violations` + эвристика | +| TC-08 | **Слайдо-источник:** парс через `parse_slides` из `scripts/build_presentation.py` (один парсер — D4): ≥ 12 слайдов, нумерация сквозная с 1, на каждом ≥ 1 тезис; нормативные биты нарратива FR-4 присутствуют (подстроки: проблема/решение/сценарии/тираж/статус) | импорт чистой функции (прецедент `test_bootstrap_script.py`) | +| TC-09 | **NFR-2 машинно:** подстрока `pptx` отсутствует в `requirements*` и `Dockerfile` | чтение файлов | +| TC-10 | **Указатели:** `README.md` ссылается на `docs/overview/`; `CLAUDE.md` несёт указатель на витрину; `CHANGELOG.md` несёт `ORCH-011` | подстроки | + +Скоуп FORBIDDEN-скана — **полнотекстовый** (не только fenced, в отличие от ORCH-102 TC-05): +витрина по построению не дублирует дефолты/хост-специфику даже в прозе (NFR-3), упоминать +боевые литералы ей незачем → ложно-красных нет, а защита шире. Существующие тесты не +ослабляются; новые попадают в существующие гейты (`check_ci_green`/`check_tests_passed`/ +merge-gate re-test/coverage ORCH-027) автоматически — **новый QG НЕ регистрируется** (ТЗ §6). + +Привязка: BR-8, FR-7, AC-4, AC-5, AC-10, AC-11, AC-12. + +### D7 (исход OQ-5) — Reviewer-ось обзорных доков: точечная правка промпта НУЖНА + +**Решение: расширить существующую ось ORCH-079 в `.openclaw/agents/reviewer.md` точечной +врезкой, называющей витрину явно.** Обоснование: по букве ось привязана к `README.md` +«Известные ограничения» («если PR закрывает/меняет пункт из README…»); витрина под букву не +подпадает, а история ORCH-079 показала, что общего правила «документация = golden source» +для обзорных доков недостаточно — ось работает, когда названа явно (❌→✅-паттерн). Норматив +правки: + +- В оси 4 «Документация» и в соответствующем ❌→✅-пункте `` существующая + формулировка ORCH-079 дополняется: *PR меняет функциональность, описанную в витрине + `docs/overview/` (стадии, гейты, агенты, интеграции, способности из business.md), а витрина + не обновлена → finding ≥ P1* — **расширение трактовки той же оси, не новая ось**. +- Канон 52d сохраняется байт-в-байт: 5 XML-секций и их порядок не меняются, verdict-ключ + `verdict: APPROVED|REQUEST_CHANGES` не трогается; правка — добавление текста внутрь + существующих секций (паттерн самой ORCH-079). +- `tests/test_agent_prompts_canon.py` расширяется ассертом на упоминание витрины в оси + обзорных доков (анти-регресс; существующие ассерты остаются зелёными). +- Зеркальная правка правила №6 `CLAUDE.md` («Reviewer проверяет…») — упоминание витрины. + +Привязка: BR-7, FR-6, AC-9. + +### D8 — Индекс: маршруты аудиторий и норматив сопровождения; указатели репо + +**Маршруты (FR-5, нормативный состав):** индекс несёт три явных маршрута с упорядоченными +списками «что читать»: +- **«Я заказчик»:** `business.md` → сценарии → `presentation.md` → + `docs/deployment/LITE_SETUP.md`/`BUNDLED_SETUP.md`; +- **«Я менеджер проекта»:** `business.md` → `tech-pipeline.md` (конвейер, статусная модель + Plane, человеческие гейты) → `tech-observability.md`; +- **«Я разработчик»:** `tech-*` (1→7) → `docs/architecture/README.md` → `internals.md` → + `docs/_standards/` → реестр ADR → `CLAUDE.md`. + +**Норматив сопровождения (FR-6, формулировка по образцу NFR-5 ORCH-102/103):** в индексе — +явная норма «**изменил функциональность платформы → обнови витрину `docs/overview/` в том же +PR**» (+ указание, какой файл какому классу изменений соответствует). Указатели: +- `CLAUDE.md`: в правило №2 («Документация = golden source») добавляется указатель на витрину + и норматив; правка правила №6 — D7; строка о витрине в разделе «Структура» (`docs/`). +- `README.md`: ссылка на витрину в начале (рядом с «Архитектура») — «единая точка входа в + документацию системы». +- `CHANGELOG.md`: запись `docs:` по ORCH-011. + +Привязка: BR-6, BR-7, BR-9, FR-5, FR-6, AC-8, AC-9, AC-11. + +### D9 — Границы изменения; 07/08 — N/A; исход OQ-4; эскалация не требуется + +- **Дифф задачи:** `docs/overview/` (10 файлов, D1), `tests/test_system_docs.py` (D6), + `scripts/build_presentation.py` (D4), правки `.openclaw/agents/reviewer.md` + + `tests/test_agent_prompts_canon.py` (D7), `README.md`/`CLAUDE.md`/`CHANGELOG.md` (D8), + `.gitignore` (+`build/`, D5), ADR-пакет work item + сквозной adr-0039 + секция в + `docs/architecture/README.md`. **`src/**`, `docker-compose.yml`, `Dockerfile`, + `requirements*` — ноль изменений** (NFR-1; машинный гард — TC-09); любое отклонение — только + новым ADR. +- `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict ключи/схема БД — байт-в-байт; новых + эндпоинтов/флагов/kill-switch нет (выключать нечего: доки и dev-скрипт не исполняются + конвейером). +- **`07-infra-requirements.md` / `08-data-requirements.md` — N/A** (прецедент ORCH-102 D9): + топология не меняется (ни контейнера, ни порта, ни маунта), схема БД не меняется (ТЗ §5). + Dev-venv для генерации `.pptx` — не инфра-предусловие конвейера: создаётся ad-hoc человеком + при сборке презентации (процедура — `presentation.md`). +- **Исход OQ-4 (compiled-wiki/экспорт):** вне объёма v1 — зафиксировано; репозиторий — + единственный источник истины («канон не форкается», ORCH-009 BR-2). Follow-up work item не + заводится автоматически: потребность в wiki-экспорте — решение Владельца после приёмки + витрины (если витрина в репо закрывает D-2/D-3, экспорт не нужен вовсе). +- **Объём одного прогона (R-3):** допущение BRD §6 принимается; приоритет при дефиците объёма: + каркас+индекс → tech-pipeline/tech-agents (машинно-сверяемые) → business → остальные tech → + presentation+скрипт. Молчаливое сокращение запрещено — недоезд = эскалация разбиением. +- **Self-hosting (NFR-5):** прод-контейнер не рестартится; выкат — штатный конвейер + (deploy-staging 8501 → Confirm Deploy). Для enduro-trails изменение инертно (общих + артефактов нет). +- **Эскалация:** `arch:major-change` не требуется (нет новой стадии/компонента/смены БД — + docs-канон); ТЗ удовлетворимо без нарушения принципов — возврат в анализ не нужен. + +## Альтернативы + +- **Расширить `README.md` вместо нового раздела** — отвергнуто: README — тех-витрина с + собственной ролью (и осью ORCH-079); бизнес-уровень + 7 блоков + маршруты раздули бы его в + монолит против NFR-6; D-3 предполагает выделенное «единое место». +- **`docs/system/` как имя каталога** — отвергнуто: «overview» точнее передаёт роль (обзор для + входа), рекомендация аналитика, прецедентов коллизии нет. +- **Монолит `tech.md` (или пара business/tech)** — отвергнуто: блоки устаревают с разным + темпом; точечные правки и пофайловые ассерты тестов дешевле на 7 файлах (NFR-6). +- **Marp / pandoc для PPTX** — отвергнуто (D4): Node+Chromium-тулчейн и растровые слайды + (Marp) / ограниченная тёмная тема через бинарный reference-doc (pandoc); python-pptx даёт + редактируемый текст и код-как-дизайн с одним pip-пакетом вне прод-образа. +- **Коммитить собранный `.pptx`** — отвергнуто (D5): недиффуемый, тестами не проверяемый, + молча устаревает (живой пример — `PRODUCT_VISION.pptx` без пути генерации); BR-5 требует + воспроизводимость, не бинарь. +- **Жёсткий снапшот-тест контента витрины (хэши/полные списки компонентов)** — отвергнуто: + превратил бы каждую docs-правку в красный CI (ложная жёсткость); тесты держат только + машинно-проверяемые факты, derive из кода (стадии/гейты/агенты), остальное — за reviewer. +- **Не править промпт reviewer (положиться на общее правило)** — отвергнуто (D7): по букве ось + ORCH-079 привязана к README; сам ORCH-079 существует потому, что общего правила для обзорных + доков не хватило; одна строка расширения дешевле гниющей витрины. +- **Автогенерация витрины из кода (autodoc)** — отвергнуто: явно вне объёма (BRD §2.2); + derive-from-code остаётся в тестах (сверка), не в генерации текста. + +## Последствия + +- **+** Единая точка входа для трёх аудиторий закрывает корневую проблему фрагментации + (BRD §1.2); презентация собирается за одну команду из версионируемого источника. +- **+** Машинно-проверяемые факты витрины (стадии/гейты/агенты/ссылки/гигиена/чистота + prod-зависимостей) — CI-гарантии (TC-01…TC-10), а не обещания: дрейф ловится тестом, гниение + прозы — расширенной reviewer-осью (D7). +- **+** Нулевой риск рантайма: docs+tests+dev-скрипт, конвейер байт-в-байт, kill-switch не + нужен; для enduro-trails инертно. +- **−** Новый golden source = новая обязанность сопровождения каждого функционального PR — + принято осознанно (в этом смысл задачи), митигировано link-first (правится одна строка-резюме, + не трактат), нормативом в индексе/CLAUDE.md и осью reviewer. +- **−** Разрешённый машинно-сверяемый дубль (стадии/гейты/агенты в `tech-pipeline.md`/ + `tech-agents.md`) — двойная запись фактов кода; защищён derive-тестами TC-03…TC-05 + (прецедент TC-02b ORCH-102). +- **−** Правка промпта reviewer — расширение поверхности канона 52d; митигировано: только + добавление внутрь существующих секций, анти-регресс `test_agent_prompts_canon.py`. +- **−** `.pptx` не в репо — показ «здесь и сейчас» требует одной команды сборки; принято + (Владелец собирает deck при необходимости; альтернатива — гниющий бинарь — хуже). +- **Откат:** удалить `docs/overview/`, `tests/test_system_docs.py`, + `scripts/build_presentation.py`, вернуть точечные правки README/CLAUDE/CHANGELOG/.gitignore/ + reviewer.md — состояние 1:1, ни миграций, ни состояния (ТЗ §7). + +## Ссылки + +- BRD: `docs/work-items/ORCH-011/01-brd.md` (решения Владельца D-1…D-4, факты §1.2) +- TRZ: `docs/work-items/ORCH-011/02-trz.md` (FR-1…FR-7, OQ-1…OQ-5) +- Acceptance: `docs/work-items/ORCH-011/03-acceptance-criteria.md` (AC-1…AC-12) +- Риски: `docs/work-items/ORCH-011/10-tech-risks.md` +- Сквозной ADR: `docs/architecture/adr/adr-0039-system-overview-docs-canon.md` +- Сверено по коду/репо: `src/stages.py::STAGE_TRANSITIONS` (9 стадий + `cancelled`), + `src/qg/checks.py::QG_CHECKS` (14 проверок), `.openclaw/agents/*.md` (6 промптов; ось + ORCH-079 в `reviewer.md`), `docs/PRODUCT_VISION.md` §1–2 (+ устаревшая схема конвейера §2), + `docs/PRODUCT_VISION.pptx` (бинарь без пути генерации), `tests/test_lite_setup_doc.py` / + `test_bundled_setup_doc.py` (паттерн структурных доков-тестов), + `tests/test_no_host_hardcodes.py` (`FORBIDDEN`, `find_violations`), + `tests/test_qg_registry_snapshot.py` (импорт QG_CHECKS), `tests/test_bootstrap_script.py` + (импорт чистых функций из `scripts/`), `.gitignore` +- Инварианты соседних решений: adr-0019 (стандарт доков), adr-0021/ORCH-092 (канон промптов + 52d), adr-0023 (ось обзорных доков ORCH-079), adr-0029 (порядок под-гейтов), adr-0037/0038 + (deployment-каноны — ссылаемся, не форкаем), ORCH-041/074/081 (модель/эффорт), + ORCH-066 (статусная модель), `docs/_standards/PIPELINE_DOCS.md` §4 (ADR-naming), + `docs/_standards/TRACEABILITY.md` (маркеры) diff --git a/docs/work-items/ORCH-011/10-tech-risks.md b/docs/work-items/ORCH-011/10-tech-risks.md new file mode 100644 index 0000000..5e63bd6 --- /dev/null +++ b/docs/work-items/ORCH-011/10-tech-risks.md @@ -0,0 +1,40 @@ +--- +work_item: ORCH-011 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-11 +model_used: claude-opus-4-8 +--- + +# 10 — Технические риски: ORCH-011 — Полная документация системы мультиагентов (витрина + PPTX) + +Work Item: **ORCH-011** · Repo: **orchestrator** · Стадия: architecture + +> Информационный (гейтом не парсится). Перечисляет риски реализации и их митигейшн. +> Базовые бизнес-риски R-1…R-5 — BRD §8; здесь — их техническая детализация + новые. + +## Реестр рисков + +| ID | Риск | Вер. | Влия. | Митигейшн | +|----|------|------|-------|-----------| +| TR-1 | **Гниение витрины** (R-1): self-hosting темп быстро устаревает снапшот; живой пример уже в репо — схема конвейера в `PRODUCT_VISION.md` §2 потеряла `deploy-staging`/`cancelled` | Выс. | Сред. | Машинно-проверяемые факты держат derive-тесты (ADR-001 D6 TC-03…TC-05: стадии/гейты/агенты импортом из кода); проза — норматив сопровождения в индексе + расширенная reviewer-ось (D7); link-first сводит правку к одной строке-резюме | +| TR-2 | **Второй источник истины** (R-2): дубль деталей architecture/README в витрине → противоречия | Сред. | Сред. | Норматив D3: запрещён дубль живых таблиц golden sources; разрешённый дубль — только машинно-сверяемый тестом факт (прецедент key-sync ORCH-102 TC-02b); контроль — AC-6 + reviewer | +| TR-3 | **Объём одного прогона** (R-3): 10 файлов + скрипт + тесты + правка промпта могут не поместиться в разумный PR | Сред. | Сред. | Модульность D1 (правки независимы); нормативный приоритет блоков при дефиците (D9); молчаливое сокращение запрещено — эскалация разбиением по штатному маршруту | +| TR-4 | **Утечка зависимости генерации в прод-образ** (R-4): `python-pptx` случайно попадает в `requirements*`/`Dockerfile` | Низ. | Выс. | Архитектура скрипта D4 (lazy import, запуск только вне рантайма); **машинный гард TC-09** (скан `requirements*`/`Dockerfile` на `pptx`) — попадание рвёт CI | +| TR-5 | **Ложная жёсткость анти-дрейф тестов:** слишком буквальные ассерты (точные фразы прозы) делают каждую будущую docs-правку красной → тесты начнут ослаблять | Сред. | Сред. | D6: ассерты только на стабильное (заголовки, имена из кода через импорт, относительные ссылки, биты-подстроки); снапшот-контента отвергнут явно (ADR-001 «Альтернативы») | +| TR-6 | **Регресс канона 52d при правке промпта reviewer** (D7): нарушение порядка секций / verdict-ключа | Низ. | Выс. | Правка — только добавление текста внутрь существующих секций (паттерн ORCH-079); анти-регресс `tests/test_agent_prompts_canon.py` (существующие ассерты + новый на упоминание витрины) | +| TR-7 | **Кириллица/тема в PPTX:** артефакт собирается, но рендеринг не «точный» (D-1): шрифт без кириллицы, контраст темы | Низ. | Сред. | python-pptx пишет редактируемый текст (не растр); шрифты — системные с полной кириллицей (Calibri/Arial); процедура в `presentation.md` несёт явную «Проверка:» (открыть файл, тема тёмная, кириллица читается); приёмка — AC-7 | +| TR-8 | **Парсер слайдо-источника расходится с тестом:** свой regex в тесте ≠ парсер скрипта → источник валиден для теста, но не собирается | Низ. | Сред. | Один парсер: тест импортирует `parse_slides` из `scripts/build_presentation.py` (D4/D6 TC-08; прецедент импорта из scripts — `test_bootstrap_script.py`) | +| TR-9 | **Цифры в бизнес-части не подтверждаются репо** (метрики скорости/стоимости из vision) → витрина теряет доверие / выдаёт желаемое за действительное | Сред. | Низ. | Норматив D2: числа только с внутрирепозиторным подтверждением или явной атрибуцией «оценка из PRODUCT_VISION»; новые цифры не изобретать (AC-12; reviewer проверяет) | +| TR-10 | **Путаница канона бинарей:** в репо остаётся `docs/PRODUCT_VISION.pptx` (старый паттерн), новый канон — «бинарь не коммитим» (D5) → будущий агент скопирует старый паттерн | Низ. | Низ. | Канон зафиксирован сквозным adr-0039 + нормативом в `presentation.md`; PRODUCT_VISION.pptx не трогается (чужой артефакт), но прецедентом не является — явная оговорка в ADR-001 D5 | + +## Сводный вывод + +Доминирующий класс — **риски сопровождения документации** (TR-1/TR-2/TR-5): изменение не несёт +рантайм-риска вовсе (docs+tests+dev-скрипт, `src/**` байт-в-байт, машинный гард TC-09), но +создаёт новый golden source, который без машинной сверки и явной reviewer-оси начал бы гнить с +первой же задачи. Митигация встроена в само решение (derive-тесты + link-first + норматив + +ось D7). Эскалация `arch:major-change` не требуется (нет новой стадии/компонента/смены БД); +возврат в анализ не нужен. Остаточный риск для прод-конвейера (self-hosting): **низкий** — +прод-контейнер не затрагивается, деплой штатным маршрутом, для enduro-trails изменение инертно.