orchestrator/docs/architecture/adr/adr-0039-system-overview-docs-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-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-каноны)