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