orchestrator/docs/work-items/ORCH-011/06-adr/ADR-001-system-overview-canon.md

work_item, stage, author_agent, status, created_at, model_used

work_item	stage	author_agent	status	created_at	model_used
ORCH-011	architecture	architect	proposed	2026-06-11	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 с жёсткой машинно-парсимой структурой:

## Слайд 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_<role>, 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 «Документация» и в соответствующем ❌→✅-пункте <constraints> существующая формулировка 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 (маркеры)