---
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_<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` (маркеры)
