orchestrator/docs/architecture/adr/adr-0037-lite-replication-canon.md

work_item, stage, author_agent, status, created_at, model_used

work_item	stage	author_agent	status	created_at	model_used
ORCH-102	architecture	architect	proposed	2026-06-10	claude-opus-4-8

adr-0037: Канон Lite-тиража — docs/deployment/LITE_SETUP.md + .env.watchdog.example (ORCH-102, 10a)

Статус

Proposed

Контекст

Эпик ORCH-10 (D5 «Масштаб»), тип A — Lite: раздача орк+watchdog заказчику-тестеру, окружение (Plane/Gitea/LLM/Telegram) он донастраивает сам. Фундамент 10-common (ORCH-101, adr-0036) в main: технически платформа разворачивается без правки кода, но операционно знания размазаны по 4 operations-докам, писанным для оператора НАШЕГО хоста, — заказчик не может развернуть Lite без доп-вопросов. Решения Владельца 10.06: оба типа тиража stateless; главный продукт ORCH-102 — инструкция-golden-source в репо.

Сквозной характер: вводится новый docs-раздел, новый канонический example-файл и нормативы, обязательные для всех будущих задач эпика ORCH-10 и для любого агента, меняющего шаги тиража. Детальный пакет решений (D1…D9, исходы вопросов ТЗ А-1…А-6) — work-item ADR: docs/work-items/ORCH-102/06-adr/ADR-001-lite-setup-doc-canon.md.

Решение

1. Новый docs-раздел docs/deployment/ — витрина тиража. Семантика: deployment/ — «как развернуть платформу у себя» (читатель — внешний оператор), operations/ — «как эксплуатировать наш прод». Golden source Lite — docs/deployment/LITE_SETUP.md: сквозной маршрут «голый хост → работающий конвейер» из 13 нормативных разделов (рамка → предусловия → код → конфиг/секреты → Plane → Gitea → LLM → Telegram → запуск → онбординг → smoke → stateless-проверка → траблшутинг); каждый шаг = fenced-команда + явная проверка (PASS/FAIL); хост-специфика — только плейсхолдеры. Канон не форкается: статусы/env/вебхуки — ссылками на ONBOARDING/REPLICATION/SETUP_WEBHOOKS (REPLICATION.md остаётся в operations/; перекрёстные ссылки в обе стороны). Норматив сопровождения: изменение шагов тиража → обновление LITE_SETUP.md в том же PR (правило агентов №2).
2. Compose не форкается. docker-compose.yml сам является Lite-подмножеством (ровно orchestrator + orchestrator-watchdog + orchestrator-staging за profiles: [staging]; дефолтный up -d поднимает орк+watchdog; сервисов Plane/Gitea нет) — отдельный docker-compose.lite.yml не вводится; свойство становится CI-гарантией (структурный тест через yaml.safe_load).
3. .env.watchdog.example — третий канонический env-example (рядом с .env.example/ .env.staging.example): закрывает ловушку файла-носителя (sidecar читает ТОЛЬКО .env.watchdog; ключ WATCHDOG_* в .env для него инертен). Key-set = ровно блок WATCHDOG_* из .env.example (равенство множеств держит тест); токены — плейсхолдеры; шапка несёт C-1 ORCH-100 (отдельный watchdog-бот, токен орка переиспользовать запрещено) и когерентность WATCHDOG_METRICS_URL ⇄ ORCH_DEPLOY_PROD_TARGET_PORT.
4. Норматив тиражной инсталляции Gitea: branch protection на main НЕ включать; pre-receive хуки не вводятся (подтверждение ORCH-009 ADR-001 D10 для чужих инсталляций: required-approvals/status-checks ломают PR-merge API merge-актора → ложные HOLD; защита main — конвенция + скоуп токенов + INV-4).
5. Staging-контур в Lite опционален: базовый контур заказчика = prod-оркестратор + watchdog; песочница 8501 нужна только при self-hosting развитии платформы у заказчика (регистрация проекта orchestrator); guard ORCH-058 (staging-порт ≠ прод-порт) действует.
6. Анти-дрейф — постоянная CI-гарантия: tests/test_lite_setup_doc.py (структурный, без сети/LLM): разделы/кирпичи дока, env-ключи дока ⊂ .env.example, key-sync watchdog-example, compose-подмножество, stateless-норматив + отсутствие секретов/боевых литералов в fenced-блоках (реюз центрального FORBIDDEN из tests/test_no_host_hardcodes.py импортом), перекрёстность REPLICATION→LITE_SETUP + CHANGELOG.

Что НЕ меняется

src/**, docker-compose.yml, Dockerfile, scripts/**; STAGE_TRANSITIONS, состав QG_CHECKS, семантика check_*, machine-verdict ключи, схема БД — байт-в-байт. Новый QG не регистрируется (структурные тесты попадают в существующие гейты). Прод-контейнер в рамках задачи не рестартуется (выкат — штатно: staging 8501 → Confirm Deploy).

Альтернативы

• Инструкция в docs/operations/ — отвергнуто: другой целевой читатель; путь зафиксирован Владельцем (D-4).
• docker-compose.lite.yml — отвергнуто: вторая правда о сервисах = дрейф-поверхность.
• Pre-receive/branch protection как «защита main» — отвергнуто: класс инцидента ORCH-063 (ложные HOLD merge-актора); пересмотр — только отдельным ADR.
• Без example-файла watchdog (шаг прозой) — отвергнуто: двусмысленность файла-носителя остаётся; example + key-sync тест надёжнее.

Последствия

• Type A эпика ORCH-10 закрыт продуктом-инструкцией; Type B (Bundled) строится поверх (переиспользует разделы Lite). Полнота инструкции и compose-подмножество защищены CI.
• Цена: новый golden source требует сопровождения (норматив «в том же PR» + структурный тест рвёт CI при дрейфе); осознанный дубль ключей WATCHDOG_* в двух example-файлах — под key-sync тестом.
• Откат: удалить docs/deployment/, тест и .env.watchdog.example, вернуть строку REPLICATION.md §1 — состояние 1:1 (docs+tests, без миграций).

Связи

adr-0036 (ORCH-101 — фундамент 10-common; этот ADR строит слой Lite поверх), adr-0035 (ORCH-009 — onboarding-CLI/kit переиспользуются маршрутом §5/§6/§10; D10 подтверждён п.4), adr-0033 (ORCH-100 — sidecar-watchdog; C-1 независимый Telegram-канал закреплён в example), adr-0008 (ORCH-058 — staging-порт guard, вилка staging п.5), adr-0027/INV-4 (merge-актор — основание запрета branch protection). Детально — docs/work-items/ORCH-102/06-adr/ADR-001-lite-setup-doc-canon.md, docs/work-items/ORCH-102/10-tech-risks.md.