architect(ET): auto-commit from architect run_id=633

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-каноны)