---
work_item: ORCH-102
stage: analysis
author_agent: analyst
status: ready-for-review
created_at: 2026-06-10
model_used: claude-opus-4-8
---

# 01 — BRD: ORCH-102 — ORCH-10a Lite-тираж: перенос орк+watchdog + полная инструкция донастройки окружения

Work Item: **ORCH-102** · Repo: **orchestrator** (self-hosting) · Стадия: analysis
Заказчик: Слава · Эпик: **ORCH-10** (домен D5 «Масштаб», `docs/epics/self-evolution.md`) · Тип: **A — Lite**

---

## 1. Бизнес-контекст и проблема

### 1.1. Цель эпика ORCH-10
Тираж платформы — РАЗДАЧА текущей функциональности нескольким заказчикам **на тест**.
Решения Владельца 10.06 (приняты как требования, см. §1.4): ДВА типа тиража, ОБА **stateless**
(наши задачи/данные/секреты НЕ переносим — чистый старт):

- **Тип A (Lite)** — переносим ТОЛЬКО орк+watchdog на новую инфру; окружение
  (Plane / Gitea / LLM / Telegram) заказчик донастраивает сам **по чёткой инструкции**.
- **Тип B (Bundled)** — весь стек одним комплектом (отдельная задача эпика, вне ORCH-102).

### 1.2. Проблема, которую закрывает ORCH-102
Фундамент **10-common (ORCH-101) уже в `main`**: все хост-значения параметризованы env
(`docker compose config` без переменных = боевое поведение 1:1), секреты выпускаются заново
(`scripts/gen_secrets.py`), есть smoke-процедура с PASS/FAIL (`docs/operations/REPLICATION.md` §4)
и анти-регресс `tests/test_no_host_hardcodes.py`. **Технически** платформа разворачивается на
чужом хосте без правки кода.

**Операционно** — нет: знания размазаны по 4+ документам, каждый из которых писался для
оператора НАШЕГО хоста, а не для заказчика на чистой инфре:

| Документ | Что покрывает | Чего не хватает для Lite |
|----------|---------------|--------------------------|
| `docs/operations/REPLICATION.md` | карта env, секреты, smoke | явно НЕ описывает установку/подключение Plane/Gitea (анти-скоуп Р-5 ORCH-101) |
| `docs/operations/ONBOARDING.md` | онбординг проекта (статусы/лейблы/репо/kit/реестр) | предполагает уже работающий оркестратор и наш хост |
| `docs/operations/SETUP_WEBHOOKS.md` | формат вебхуков Plane/Gitea | примеры с боевыми URL (`mva154`), не generic |
| `docs/operations/INFRA.md` | топология/рестарты нашего хоста | не инструкция «с нуля» |

Заказчик сегодня **не может развернуть Lite без доп-вопросов** — отсутствует единый сквозной
маршрут «голый хост → работающий конвейер». Главный продукт ORCH-102 — **ИНСТРУКЦИЯ**
`docs/deployment/LITE_SETUP.md` (golden source в репо), закрывающая этот разрыв.

### 1.3. Установленные факты (проверено по репо, не изобретать)
- **ORCH-101 смержен** (`git log`: merge #122) — ветка задачи уже содержит фундамент: env-карта
  §2 REPLICATION.md, `gen_secrets.py`, `.env.example` = канон 100% ключей старта (включая блок
  `WATCHDOG_*`), smoke §4, тесты `test_no_host_hardcodes/test_infra_parametrization/test_secrets_gen/test_replication_smoke`.
- **`docker-compose.yml` УЖЕ является compose-подмножеством Lite:** ровно три сервиса —
  `orchestrator`, `orchestrator-watchdog`, `orchestrator-staging` (последний строго за
  `profiles: [staging]`); сервисов Plane/Gitea в compose НЕТ. Дефолтный `docker compose up -d`
  поднимает ровно орк+watchdog. AC-2 достижим без форка compose — нужны фиксация в доке и
  анти-дрейф тест.
- **Plane CE не отдаёт webhook через публичный API** — на нашем хосте webhook создан напрямую в
  PostgreSQL / через UI (`SETUP_WEBHOOKS.md`). Инструкция Lite обязана дать заказчику оба пути
  (UI и DB) для ЕГО инсталляции Plane.
- **Точная модель статусов**: 22 канонических имени с группами (источник —
  `plane_sync._PLANE_NAME_TO_KEY`; таблица — `ONBOARDING.md` §1; создаёт
  `scripts/onboard_project.py apply`). Код-критичные fail-closed: `Confirm Deploy`, `STOP`
  (группа `cancelled`); в терминальных группах — только Done/Cancelled/STOP.
- **Branch protection на `main` нормативно ЗАПРЕЩЁН** (ORCH-009 ADR D10: required-approvals /
  status-checks ломают PR-merge API merge-актора → ложные HOLD). **Pre-receive хуков в платформе
  НЕТ** — защита держится конвенцией + скоупом токенов. Формулировка бизнес-запроса
  «pre-receive хуки» конфликтует с этим нормативом → вопрос архитектору (ТЗ §3.8 А-1);
  рекомендация: раздел Gitea фиксирует канон (репо+токен+webhook+«protection НЕ включать»).
- **Гэп watchdog-конфига:** compose читает `.env.watchdog` (`required: false`), но
  `.env.watchdog.example` в репо НЕТ (есть только `.env.example`/`.env.staging.example`);
  ключи `WATCHDOG_*` задокументированы внутри `.env.example`. Инструкции нужен однозначный
  рецепт настройки watchdog-бота (форма — вопрос архитектору А-4).
- **Платформенные конвенции тиража** (REPLICATION.md §1, нормативно): репо платформы обязан
  называться `orchestrator` (`SELF_HOSTING_REPO`); имена сервисов/профиля — константы;
  контейнерный layout (`/app/data`, `/repos`, `/opt/claude-code`) не параметризуется.
- **Прецедент приёмки smoke**: ORCH-101 AC-3 — воспроизводимость подтверждается прогоном на
  текущей инфре (staging-песочница `ORCH_STAGING_PORT`=8501 + sandbox-проект), без нового железа.

### 1.4. Решения Владельца (10.06) — приняты как требования
| # | Решение |
|---|---------|
| D-1 | Тиражей ДВА типа: A (Lite) и B (Bundled); ORCH-102 реализует ТОЛЬКО A. |
| D-2 | Оба типа **stateless**: наши задачи/данные/секреты не переносятся; на целевой инфре чистый старт. |
| D-3 | Lite = перенос ТОЛЬКО орк+watchdog; окружение (Plane/Gitea/LLM/Telegram) заказчик донастраивает по инструкции. |
| D-4 | Главный продукт задачи = **инструкция** `docs/deployment/LITE_SETUP.md` — golden source в репо. |
| D-5 | Зависимость: ORCH-102 ← **10-common (ORCH-101)** — выполнена (смержен), блокеров нет. |

---

## 2. Объём (scope)

### 2.1. В объёме
- **Инструкция `docs/deployment/LITE_SETUP.md`** — полная пошаговая (каждый шаг = команда +
  проверка), покрывающая сквозной маршрут: предусловия хоста (зависимости, uid/gid) → перенос
  кода орк+watchdog → конфиг (`.env` с нуля + секреты) → подключение Plane (workspace/проект,
  точная модель статусов, API-токен, webhook+HMAC) → подключение Gitea (репо, токен, webhook,
  норматив защиты `main`) → LLM-доступ (claude CLI / ключи моделей) → Telegram (бот трекера +
  watchdog-бот + chat-id) → запуск compose-подмножества → регистрация проекта
  (`ORCH_PROJECTS_JSON`, `src/projects.py`) → health-чек → smoke (из 10-common) → траблшутинг.
- **Фиксация compose-подмножества** (AC-2): документировано и защищено структурным тестом, что
  дефолтный запуск = ровно орк+watchdog, без Plane/Gitea-контейнеров.
- **Stateless-нормативы** в инструкции (AC-3): чистая БД, новые секреты, явный запрет переноса
  наших задач/данных/секретов.
- **Smoke на чистом окружении** (AC-4): воспроизводимая процедура/чек-лист (переиспользование
  REPLICATION.md §4) + зафиксированный приёмочный прогон.
- **Анти-дрейф тесты** структуры/полноты инструкции и compose-подмножества; полный pytest
  зелёный; `CHANGELOG.md`; перекрёстные ссылки (REPLICATION.md §1 границы, README — по объёму).

### 2.2. Вне объёма (явно, не делать)
- **Тип B (Bundled)** — весь стек одним комплектом: отдельная задача эпика.
- **Установка самих Plane / Gitea / Telegram / LLM-аккаунтов** — заказчик ставит по официальной
  документации вендоров; ORCH-102 покрывает только ПОДКЛЮЧЕНИЕ к оркестратору (анти-скоуп-крип,
  зеркало Р-5 ORCH-101).
- **Изменения рантайма/конвейера**: ожидаемый объём — docs+tests; `src/**` не трогается;
  `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict ключи / схема БД — байт-в-байт.
- **Перенос данных**: ни БД, ни задач, ни worktree, ни секретов (D-2).
- **Новая автоматизация** поверх существующих CLI (`gen_secrets.py`, `onboard_project.py`):
  новые скрипты не вводятся без решения архитектора.
- **Коммерческая механика раздачи** (доступ заказчика к коду, лицензии, поддержка) —
  операторский/владельческий уровень; в инструкции — параметризованный источник кода.
- **Введение pre-receive хуков / branch protection** — запрещено действующим нормативом
  ORCH-009 ADR D10 (см. §1.3); пересмотр только явным ADR архитектора.

---

## 3. Заинтересованные стороны
- **Владелец (Слава)** — раздаёт платформу заказчикам на тест; принимает инструкцию как продукт.
- **Заказчик-тестер (новый оператор)** — целевой читатель LITE_SETUP.md: разворачивает Lite на
  своей инфре без доп-вопросов; технически грамотен (linux/docker), платформу видит впервые.
- **Оператор текущего прода** — прогоняет приёмочный smoke на staging-песочнице; его прод
  (общий для enduro-trails) не должен быть затронут.
- **Будущая задача 10b (Bundled)** — переиспользует разделы Lite-инструкции; границы фиксируются
  в REPLICATION.md §1.

---

## 4. Бизнес-требования (BR)

| ID | Требование | Связь |
|----|------------|-------|
| BR-1 | Существует `docs/deployment/LITE_SETUP.md` — **полная пошаговая** инструкция Lite-тиража: по ней человек, не видевший платформу, разворачивает орк+watchdog и донастраивает окружение **без доп-вопросов**; **каждый шаг несёт команду и проверку** (ожидаемый результат / PASS-FAIL). | AC-1, FR-1, D-4 |
| BR-2 | Инструкция покрывает ВСЕ системы донастройки: Plane (workspace/проект, точная модель статусов — 22 имени с группами, API-токен, webhook+HMAC с учётом ограничения Plane CE), Gitea (репо, токен с нужными scope, per-repo webhook, норматив «branch protection `main` НЕ включать»), LLM (claude CLI: дистрибутив/node/аутентификация/`ORCH_CLAUDE_BIN`/модели), Telegram (бот трекера + ОТДЕЛЬНЫЙ watchdog-бот + получение chat-id), регистрацию проекта (`ORCH_PROJECTS_JSON` через `onboard_project.py`), health-чек, smoke. | AC-1, FR-4 |
| BR-3 | Разворачивается **compose-подмножество только орк+watchdog**: дефолтный `docker compose up -d` поднимает ровно `orchestrator`+`orchestrator-watchdog`; Plane/Gitea-контейнеров в compose нет; staging-сервис — строго за профилем. Свойство зафиксировано в доке и защищено структурным тестом. | AC-2, FR-2 |
| BR-4 | **Stateless**: инструкция предписывает чистую БД (создаётся пустой при первом старте), выпуск НОВОГО комплекта секретов (`gen_secrets.py` + чек-лист внешних токенов), и нигде не предписывает перенос наших задач/данных/секретов; в самой доке — только плейсхолдеры, ни одного реального секрета/боевого токена. | AC-3, FR-3 |
| BR-5 | **Smoke на чистом окружении** существует как воспроизводимая процедура/чек-лист с PASS/FAIL (переиспользование REPLICATION.md §4, без форка); приёмочный прогон выполнен на чистом контуре (минимум — staging-песочница + sandbox-проект, прецедент ORCH-101 AC-3) и зафиксирован в артефактах задачи. | AC-4, FR-5 |
| BR-6 | **Канон не форкается**: канонические таблицы (модель статусов, карта env, формат вебхуков) инструкция даёт ссылкой на golden source (`ONBOARDING.md`/`REPLICATION.md`/`SETUP_WEBHOOKS.md`) либо с анти-дрейф тестом при неизбежном дублировании; копируемые команды инструкции — generic (плейсхолдеры вместо боевых URL/путей). | AC-1/AC-6, FR-4, NFR-4 |
| BR-7 | Полный `pytest tests/ -q` зелёный; запись в `CHANGELOG.md`; перекрёстные доки обновлены (REPLICATION.md §1 «границы» — строка Type A → ссылка/статус; README/CLAUDE.md — по фактическому объёму, правило агентов №2/№6). | AC-5, FR-6/FR-7 |
| BR-8 | Полнота/структура инструкции защищена **структурным pytest** (анти-дрейф, по образцу `tests/test_replication_smoke.py`): исчезновение обязательного раздела/кирпича/env-ключа из дока или дрейф compose-подмножества ломает CI. | AC-6, FR-6 |

---

## 5. Нефункциональные требования (NFR)

| ID | Требование |
|----|------------|
| NFR-1 | **Self-hosting безопасность:** задача docs+tests; прод-контейнер `orchestrator` не перезапускается; прод-выкат — только штатным конвейером (staging 8501 → ручной Confirm Deploy). |
| NFR-2 | **Нулевая регрессия:** поведение рантайма не меняется (ожидаемо ноль изменений `src/**`); `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict/схема БД — байт-в-байт; существующие тесты (включая `test_no_host_hardcodes`, `test_replication_smoke`) остаются зелёными. |
| NFR-3 | **Секрет-гигиена:** ни в инструкции, ни в тестах — ни одного реального секрета/токена/боевого webhook-секрета; только плейсхолдеры и ссылки на `gen_secrets.py`; security-гейт (ORCH-022) зелёный. |
| NFR-4 | **Единый источник истины:** инструкция — маршрутизатор поверх канонов, не их копия; неизбежные дубли защищены анти-дрейф тестом (сверка с кодом/каноном импортом, не строкой). |
| NFR-5 | **Поддерживаемость golden source:** LITE_SETUP.md версионируется в репо и поддерживается агентами при каждой доработке, меняющей шаги тиража (правило агентов №2 — дока в том же PR). |
| NFR-6 | **Копируемость команд:** каждый код-блок инструкции выполняется на чистом хосте дословно после подстановки явно перечисленных плейсхолдеров (`<...>`); никаких неявных «подразумевается, что…». |

---

## 6. Допущения и ограничения
- **Поддерживаемый контур** (фиксируется в предусловиях инструкции): Linux x86_64, Docker Engine +
  Compose v2, git, python3; пользователь с правами docker; диск/память по минимальным требованиям
  (значения уточнит архитектор/инструкция). Иные ОС/архитектуры — вне гарантии Lite.
- **Заказчик сам ставит** Plane CE, Gitea, заводит Telegram-ботов и LLM-доступ (Claude
  CLI-аутентификация / ключи) — по официальным докам вендоров; наша инструкция начинается с
  «системы установлены и доступны по сети».
- **Имя репо платформы — `orchestrator`** (норматив REPLICATION.md §1 / `SELF_HOSTING_REPO`);
  инструкция не предлагает его менять.
- **Источник кода** для заказчика (clone-URL/архив) — решение Владельца; в инструкции —
  параметризованный шаг (А-6 в ТЗ).
- «Без доп-вопросов» (AC-1) операционализируется проверяемо: (а) каждый шаг несёт
  команду+проверку, (б) приёмочный smoke-прогон по инструкции на чистом контуре зафиксирован,
  (в) траблшутинг покрывает типовые отказы первичной настройки.
- Терминология бизнес-запроса «pre-receive хуки» трактуется по факту платформы (§1.3):
  канонический механизм защиты — конвенция + скоуп токенов + запрет branch protection;
  окончательная формулировка раздела Gitea — за архитектором (А-1).

---

## 7. Критерии успеха (резюме; детали — 03-acceptance-criteria.md)
- AC-1: `docs/deployment/LITE_SETUP.md` — полная пошаговая, человек разворачивает без
  доп-вопросов (каждый шаг — команда/проверка).
- AC-2: compose-подмножество только орк+watchdog (без Plane/Gitea-контейнеров).
- AC-3: stateless — чистая БД, ни одной нашей задачи/секрета.
- AC-4: smoke на чистом окружении проходит (минимум — воспроизводимая процедура/чек-лист).
- AC-5: pytest зелёный; CHANGELOG.
- AC-6 (детализация): анти-дрейф тесты структуры дока/compose; канон не форкается.
- AC-7 (детализация): self-hosting безопасность, инварианты конвейера не тронуты.

---

## 8. Риски (детали — 10-tech-risks.md, заполняет архитектор)
- R-1 — **Дрейф инструкции**: платформа развивается, шаги устаревают → структурные тесты (BR-8)
  + правило golden source (NFR-5).
- R-2 — **Форк канона**: скопированная таблица статусов/env разъедется с кодом → ссылки/анти-дрейф
  (BR-6, NFR-4).
- R-3 — **Непроверяемость «без доп-вопросов»** → операционализация через §6 (команда+проверка,
  smoke-прогон, траблшутинг).
- R-4 — **Гетерогенность хостов заказчиков** (rootless docker, иной uid, нет node) → явный
  поддерживаемый контур + предусловия с проверками (`getent group docker`, владение
  `ORCH_HOST_REPOS_DIR`).
- R-5 — **Конфликт «pre-receive» с нормативом ADR D10** → вопрос А-1 архитектору; до решения —
  канон платформы.
- R-6 — **Утечка секрета через примеры дока** → NFR-3, security-гейт, тест на отсутствие
  секретоподобных значений.
