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

---
work_item: ORCH-102
stage: architecture
author_agent: architect
status: proposed
created_at: 2026-06-10
model_used: 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`.