96 lines
8.6 KiB
Markdown
96 lines
8.6 KiB
Markdown
---
|
||
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-каноны)
|