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

# 02 — ТЗ (TRZ): ORCH-102 — ORCH-10a Lite-тираж: перенос орк+watchdog + полная инструкция донастройки окружения

Work Item: **ORCH-102** · Repo: **orchestrator** · Стадия: analysis

> ТЗ описывает **что** должно измениться и **где** (документы/контракты/тесты), выведено из BRD и
> фактического кода (аудит выполнен по репо на ветке задачи; ORCH-101 уже в `main`). **Как**
> (точная разбивка разделов дока, форма анти-дрейф тестов, исходы вопросов §3.8) — решает
> архитектор в `06-adr/`.

---

## 1. Сводка изменения

**Docs-first задача** (паттерн ORCH-077/092: документы + тесты, рантайм не трогается).
Создаётся главный продукт — инструкция `docs/deployment/LITE_SETUP.md` (golden source Lite-тиража,
новый раздел `docs/deployment/`), которая собирает существующие кирпичи 10-common
(REPLICATION/ONBOARDING/SETUP_WEBHOOKS/INFRA, `gen_secrets.py`, `onboard_project.py`, smoke §4)
в один сквозной маршрут «голый хост → работающий конвейер» для заказчика. Дополнительно:
структурные анти-дрейф тесты (полнота дока, compose-подмножество, stateless/секрет-гигиена),
перекрёстные ссылки и CHANGELOG.

Ожидаемый дифф: `docs/**`, `tests/**`, `CHANGELOG.md` (+ опционально `.env.watchdog.example` —
исход А-4). **`src/**` — ноль изменений**; конвейер
(`STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict/схема БД) — байт-в-байт.

---

## 2. Задействованные модули / пути

| Путь | Действие |
|------|----------|
| `docs/deployment/LITE_SETUP.md` | **создать** — главный продукт (полная пошаговая инструкция Lite; новый каталог `docs/deployment/`) |
| `docs/operations/REPLICATION.md` | изменить: §1 таблица границ — строка «Type A — Lite» → статус ✅ ORCH-102 + ссылка на LITE_SETUP.md |
| `tests/test_lite_setup_doc.py` | **создать** — структурные анти-дрейф проверки дока + compose-подмножества (образец: `tests/test_replication_smoke.py`) |
| `.env.watchdog.example` | создать **по исходу А-4** (канон конфигурации sidecar-watchdog для нового хоста; сейчас примера нет, compose читает `.env.watchdog` `required: false`) |
| `docs/operations/INFRA.md` | изменить при необходимости: перекрёстная ссылка на deployment-раздел (по фактическому объёму) |
| `README.md` | изменить: обзорный док — способность Lite-тиража (правило агентов №6: не выдавать открытое за решённое и наоборот) |
| `CLAUDE.md` | изменить: блок ORCH-102 в паспорте — по фактическому объёму (правило №2) |
| `CHANGELOG.md` | изменить: запись ORCH-102 |
| `src/**`, `docker-compose.yml`, `Dockerfile`, `scripts/**` | **НЕ менять** (читаются инструкцией/тестами как источник истины; любое отклонение — только через ADR архитектора) |

Кирпичи, которые инструкция **переиспользует по ссылке** (не форкает, BR-6/NFR-4):
`docs/operations/REPLICATION.md` (карта env §2, секреты §3, smoke §4),
`docs/operations/ONBOARDING.md` (статусы §1, слои Gitea/kit/реестр §2–5),
`docs/operations/SETUP_WEBHOOKS.md` (формат вебхуков, Plane CE-каверза),
`scripts/gen_secrets.py`, `scripts/onboard_project.py` (plan/apply/verify),
`.env.example` (канон 100% ключей), `GET /health|/queue|/metrics`.

---

## 3. Функциональные требования

### FR-1 — Документ `docs/deployment/LITE_SETUP.md`: состав и форма

Привязка: BR-1, BR-2. Нормативный перечень разделов (порядок = маршрут оператора; финальную
разбивку/нумерацию решает архитектор, состав — обязательный минимум):

1. **Рамка Lite** — что разворачиваем (орк+watchdog), что заказчик ставит сам (Plane/Gitea/
   Telegram/LLM), границы vs 10-common vs Bundled (ссылка на REPLICATION.md §1), платформенные
   конвенции (репо `orchestrator`, имена сервисов, контейнерный layout — не менять).
2. **Предусловия хоста** («зависимости, uid/gid» из бизнес-запроса): поддерживаемый контур
   (Linux x86_64, Docker Engine + Compose v2, git, python3); node + дистрибутив claude-code на
   хосте (`ORCH_HOST_NODE_BIN`, `ORCH_HOST_CLAUDE_CODE_DIR` — пути под маунты); пользователь и
   владение каталогами: `ORCH_RUN_UID/GID` = uid владельца `ORCH_HOST_REPOS_DIR` (инвариант
   ORCH-040), `ORCH_DOCKER_GID` — `getent group docker`; ssh-ключи деплой-хука
   (`ORCH_HOST_SSH_DIR`); свободные порты (`ORCH_DEPLOY_PROD_TARGET_PORT`=8500,
   `ORCH_STAGING_PORT`=8501). Каждое предусловие — команда проверки.
3. **Перенос кода орк+watchdog**: получение чекаута репо `orchestrator` на хост в
   `ORCH_DEPLOY_HOST_REPO_PATH` (источник кода — параметризованный шаг, исход А-6); НИКАКИХ
   данных/БД/`.env` с боевого хоста (D-2). Watchdog отдельно не переносится — код в `watchdog/`
   того же репо, образ собирается локально compose'ом.
4. **Конфигурация**: `.env` строится с нуля от `.env.example` (канон); webhook-секреты —
   `python3 scripts/gen_secrets.py [--write]`; карта переменных — ссылкой на REPLICATION.md §2;
   в доке явно — **обязательные ключи нового хоста**: `ORCH_PLANE_API_URL/WEB_URL/WORKSPACE_SLUG`,
   `ORCH_PLANE_API_TOKEN`, `ORCH_GITEA_URL/PUBLIC_URL/OWNER`, `ORCH_GITEA_TOKEN`, оба
   webhook-секрета, `ORCH_TELEGRAM_BOT_TOKEN/CHAT_ID`, `ORCH_PROJECTS_JSON` (обязателен:
   встроенный fallback несёт UUID исходного хоста), хост-параметры `ORCH_AGENT_HOME_DIR`/
   `ORCH_HOST_*`/`ORCH_RUN_*`/`ORCH_DOCKER_GID`, когерентность портов
   (`ORCH_DEPLOY_PROD_TARGET_PORT` ⇄ `WATCHDOG_METRICS_URL` ⇄ `ORCH_POST_DEPLOY_BASE_URL`).
5. **Подключение Plane** (инсталляция заказчика): создать workspace/проект; **точная модель
   статусов** — 22 канонических имени с группами: создаёт `onboard_project.py apply`, таблица —
   ссылкой на ONBOARDING.md §1 (без форка; fail-closed `Confirm Deploy`/`STOP` упомянуть явно);
   выпуск API-токена (Workspace Settings → API tokens) + команда проверки; **webhook+HMAC**:
   URL `…/webhook/plane`, секрет из `gen_secrets.py`, заголовок `X-Plane-Signature`; каверза
   Plane CE «webhook не экспонирован в /api/v1» — оба пути (UI и прямой SQL, generic-вариант
   команд SETUP_WEBHOOKS.md с плейсхолдерами).
6. **Подключение Gitea** (инсталляция заказчика): репо (`onboard_project.py` или вручную),
   токен (scope `repo`, `admin:repo_hook`) + проверка, per-repo webhook (events
   `push`/`pull_request`/`status`, `X-Gitea-Signature`, **ОДИН глобальный секрет на все репо**);
   норматив защиты `main` — по исходу А-1 (канон: branch protection НЕ включать, ORCH-009 ADR D10).
7. **LLM-доступ (claude CLI)**: дистрибутив claude-code и node на хосте (пути = маунты compose),
   `ORCH_CLAUDE_BIN`; аутентификация CLI на хосте (каталог `ORCH_HOST_CLAUDE_DIR` +
   `ORCH_HOST_CLAUDE_JSON` — монтируются в контейнер; команда первичного логина/проверки —
   `claude --version` / минимальный вызов); конфигурация моделей — `ORCH_AGENT_MODEL_*` /
   `ORCH_AGENT_EFFORT_*` (резолв ORCH-41; дефолты канона — в `.env.example`).
8. **Telegram**: бот трекера (BotFather `/newbot` → `ORCH_TELEGRAM_BOT_TOKEN`), получение
   `chat_id` (воспроизводимая команда, например через `getUpdates`), проверка `getMe`;
   **отдельный** watchdog-бот (`WATCHDOG_TG_BOT_TOKEN/CHAT_ID` — независимый канал, C-1
   ORCH-100, токен орка переиспользовать запрещено) — размещение ключей по исходу А-4
   (`.env.watchdog`).
9. **Запуск compose-подмножества**: `docker compose config` (резолв без ошибок) →
   `docker compose up -d --build` → поднимаются ровно `orchestrator` + `orchestrator-watchdog`
   (AC-2); staging-профиль — опционально/когда нужен (исход А-5); health-чек:
   `GET /health` → 200 `"status":"ok"`, `GET /queue`/`GET /metrics` → штатный JSON
   (`schema_version: 1`).
10. **Регистрация проекта заказчика**: `onboard_project.py plan → apply → verify`
    (Plane-проект+статусы+лейблы `autoApprove`/`autoDeploy`/`Bug`, Gitea-репо+webhook, kit,
    merged `ORCH_PROJECTS_JSON`) → внести строку в `.env` → управляемый рестарт → проверка
    `/health`+`/queue` (маршрут ONBOARDING.md, ссылкой; в Lite-доке — последовательность команд).
11. **Smoke** (AC-4): чек-лист REPLICATION.md §4 (шаги 0–5, опционально 6 до `done`) —
    переиспользовать ссылкой + Lite-специфичные предусловия; критерий «конвейер доехал»:
    задача в БД → analyst-job в `/queue` → артефакты `01–04` в ветке задачи.
12. **Stateless-проверка** (AC-3): первый старт создаёт пустую БД (`data/` чист); `GET /queue` —
    нулевые счётчики, ни одной задачи `ORCH-*`/`ET-*`; явная нормативная строка «данные/задачи/
    секреты боевого хоста НЕ переносятся».
13. **Траблшутинг** первичной настройки: минимум — webhook 401/HMAC mismatch; «задача не
    появилась» (реестр/`ORCH_PROJECTS_JSON`/webhook); claude CLI не аутентифицирован/не найден;
    `docker.sock` permission denied (`ORCH_DOCKER_GID`); права `/repos` (uid mismatch,
    ORCH-040/057); Telegram молчит (токен/chat-id). Каждый пункт — симптом → команда
    диагностики → лечение.

**Форма (NFR-6, BR-1):** каждый шаг — исполняемая команда (fenced code block) + явная проверка
(«Проверка:» / PASS-FAIL / ожидаемый вывод); все хост-специфичные значения в командах — только
плейсхолдеры `<...>` или `$ENV_VAR` (боевые `mva154`/`82.22.50.71`/реальные токены — запрещены);
язык — русский (канон доков платформы).

### FR-2 — Compose-подмножество (AC-2)

Привязка: BR-3. Зафиксировать (в доке + тестом), что Lite-развёртывание использует
существующий `docker-compose.yml` БЕЗ форка:

- множество сервисов файла — ровно `{orchestrator, orchestrator-watchdog, orchestrator-staging}`;
- `orchestrator-staging` строго за `profiles: [staging]` → дефолтный `docker compose up -d`
  поднимает ровно орк+watchdog;
- сервисов/образов Plane/Gitea в compose НЕТ (и тест не даст появиться молча);
- форма фиксации (существующий файл vs отдельный lite-вариант) — исход А-2; ТЗ-рекомендация:
  существующий файл (он уже является подмножеством — факт BRD §1.3), отдельный файл не плодить.

### FR-3 — Stateless-нормативы (AC-3)

Привязка: BR-4. Инструкция обязана: (а) предписывать чистый старт — пустой `data/` (БД создаётся
`init_db()` при первом старте), `.env` только с нуля; (б) предписывать выпуск НОВЫХ секретов
(`gen_secrets.py` + чек-лист REPLICATION.md §3.2) и нести норматив «боевые секреты/данные/задачи
не копируются»; (в) содержать проверку чистоты (FR-1 п.12); (г) сама не содержать реальных
секретов (NFR-3; проверяется тестом FR-6 и security-гейтом ORCH-022).

### FR-4 — Покрытие донастройки окружения без форка канона (AC-1)

Привязка: BR-2, BR-6. Per-system разделы FR-1 п.5–8 обязаны быть полными (заказчик не ходит за
ответами вовне репо), при этом канонические данные даются ссылкой на golden source:

| Данные | Golden source | В LITE_SETUP.md |
|--------|---------------|------------------|
| 22 статуса + группы | `plane_sync._PLANE_NAME_TO_KEY` / ONBOARDING.md §1 | ссылка + критичные fail-closed имена (`Confirm Deploy`, `STOP`) |
| Карта env / хост-параметры | REPLICATION.md §2 / `.env.example` | ссылка + список обязательных ключей нового хоста |
| Формат вебхуков / Plane CE-каверза | SETUP_WEBHOOKS.md | ссылка + generic-команды с плейсхолдерами |
| Онбординг проекта | ONBOARDING.md / `onboard_project.py` | ссылка + последовательность команд Lite-маршрута |
| Smoke | REPLICATION.md §4 | ссылка + Lite-предусловия |

Если архитектор решит дублировать таблицу (читаемость) — дубль защищается анти-дрейф тестом
(сверка импортом из `src/plane_sync.py` / парсингом `.env.example`), не строковой копией.

### FR-5 — Smoke на чистом окружении (AC-4)

Привязка: BR-5. Состав: (а) в LITE_SETUP.md — smoke-раздел (FR-1 п.11) как воспроизводимый
чек-лист с PASS/FAIL на каждый шаг; (б) приёмочный прогон процедуры на чистом контуре — минимум
staging-песочница (порт `ORCH_STAGING_PORT`, изолированная БД `./data/staging`) + одноразовый
sandbox-проект (прецедент ORCH-101 AC-3 / ONBOARDING.md §5.2), без нового железа; (в) результат
прогона фиксируется в артефактах задачи (`13-test-report.md` / `15-staging-log.md`); (г) прогон
на реальном новом хосте — желателен, но НЕ требование приёмки (нет железа в контуре задачи).

### FR-6 — Анти-дрейф тесты (BR-8)

Привязка: BR-3, BR-6, BR-8. Новый `tests/test_lite_setup_doc.py` (структурный, без сети/LLM;
образец — `tests/test_replication_smoke.py`):

1. док существует по канонному пути; несёт обязательные разделы/кирпичи FR-1 (минимум:
   `gen_secrets.py`, `onboard_project.py`, `docker compose`, `/health`, `/queue`, `/metrics`,
   `ORCH_PROJECTS_JSON`, webhook-секреты, `X-Plane-Signature`/`X-Gitea-Signature`,
   `getent group docker`, `Confirm Deploy`/`STOP`, Telegram-боты обоих каналов, маркеры
   PASS/FAIL/«Проверка»);
2. каждый env-ключ `ORCH_*`/`WATCHDOG_*`, упомянутый в доке, существует в `.env.example`
   (анти-опечатка/анти-дрейф канона);
3. compose-подмножество: парсинг `docker-compose.yml` — ровно 3 сервиса, staging за профилем,
   ни одного сервиса/образа `plane*`/`gitea*` (AC-2);
4. stateless/секрет-гигиена: нормативная строка «не копиру…» присутствует; в доке нет
   секретоподобных значений (эвристика по образцу security-паттернов) и боевых литералов
   (`mva154`, `duckdns`, `82.22.50.71`) в копируемых код-блоках;
5. перекрёстность: REPLICATION.md §1 ссылается на LITE_SETUP.md; `CHANGELOG.md` несёт ORCH-102.

Точная нарезка по тест-модулям — за developer (план — `04-test-plan.yaml`); существующие тесты
не правятся (кроме согласованных структурных дополнений).

### FR-7 — Перекрёстная документация (BR-7)

Привязка: BR-7. REPLICATION.md §1 (строка Type A — Lite → ✅ + ссылка); README.md — способность
Lite-тиража в обзоре (правило №6); CLAUDE.md — по фактическому объёму; CHANGELOG.md — запись.
INFRA.md — ссылка на deployment-раздел при необходимости.

---

## 3.8. Вопросы архитектору (решаются в `06-adr/`, не в ТЗ)

- **А-1 — «pre-receive хуки» vs норматив ADR D10 (ORCH-009):** бизнес-запрос упоминает
  pre-receive хуки, но в платформе их нет, а branch protection на `main` нормативно запрещён
  (ломает PR-merge API merge-актора). Что фиксирует раздел Gitea? Рекомендация ТЗ: канон —
  репо+токен+webhook+явный норматив «branch protection НЕ включать»; pre-receive не вводить;
  отклонение — только отдельным ADR с анализом совместимости с merge-актором (ORCH-093/INV-4).
- **А-2 — форма compose-подмножества:** существующий `docker-compose.yml` (уже = подмножество)
  + документация/тест vs отдельный `docker-compose.lite.yml`. Рекомендация: существующий, без
  форка (нулевой дрейф, AC-2 держит тест).
- **А-3 — размещение дока:** бизнес-запрос фиксирует `docs/deployment/LITE_SETUP.md` (новый
  раздел `docs/deployment/`); REPLICATION.md живёт в `docs/operations/`. Подтвердить layout
  (deployment как витрина тиража vs operations) и перекрёстные ссылки; отступление от пути
  бизнес-запроса — только явным решением.
- **А-4 — канон watchdog-конфига нового хоста:** compose читает `.env.watchdog`
  (`required: false`), примера-файла нет; ключи `WATCHDOG_*` канонизированы в `.env.example`.
  Добавить `.env.watchdog.example` (симметрия с `.env.staging.example`) или документировать
  шаг «создай `.env.watchdog` с двумя ключами» в LITE_SETUP? Рекомендация: example-файл +
  упоминание в доке (меньше шансов перепутать файл-носитель).
- **А-5 — staging-контур в Lite-инструкции:** обязателен ли запуск `orchestrator-staging` у
  заказчика? Рекомендация: опционален — нужен только если заказчик регистрирует проект
  `orchestrator` (self-hosting развитие платформы); для «раздачи на тест» базовый контур =
  prod-инстанс + watchdog; в доке — явная вилка.
- **А-6 — источник кода для заказчика:** clone-URL (зеркало/доступ к нашему Gitea) vs архив.
  В доке — параметризованный шаг `git clone <ORCHESTRATOR_GIT_URL>`; конкретику источника
  фиксирует Владелец (вне репо).

---

## 4. Изменения API

Нет. Существующие `GET /health` / `/queue` / `/metrics` переиспользуются инструкцией read-only;
новые эндпоинты не вводятся.

## 5. Изменения схемы БД

Нет.

## 6. Требования к новым/изменённым QG checks

Нет. `QG_CHECKS`/`check_*`/machine-verdict ключи не меняются. Новые структурные тесты (FR-6) —
обычный pytest: попадают в существующие гейты (`check_ci_green`/`check_tests_passed`/merge-gate
re-test/coverage-гейт ORCH-027) автоматически, без регистрации нового QG.

## 7. Совместимость / регресс

- **Нулевая регрессия (NFR-2):** дифф — docs+tests (+опц. `.env.watchdog.example`); рантайм не
  меняется; kill-switch не требуется (нечего выключать); полный `pytest tests/ -q` зелёный,
  существующие структурные тесты (`test_no_host_hardcodes`, `test_replication_smoke`,
  `test_infra_parametrization`, `test_onboarding_*`) не ослабляются.
- **Обратимость:** удаление дока/тестов возвращает состояние 1:1 (никаких миграций/состояния).
- **Self-hosting (NFR-1):** прод-контейнер не рестартится; выкат — штатный конвейер
  (deploy-staging 8501 → ручной Confirm Deploy). Для enduro-trails изменение инертно.
- **Секрет-гигиена (NFR-3):** в доке/тестах только плейсхолдеры; security-гейт (ORCH-022,
  `17-security-report.md`) обязан остаться `PASS`.
- **Инварианты соседних маркеров (правило №9):** ORCH-101 (дефолт = боевое значение; канон
  `.env.example`; конвенции тиража REPLICATION §1), ORCH-009 (ADR D10 — без branch protection;
  onboarding-CLI ничего не удаляет), ORCH-100 (независимый Telegram-канал watchdog, C-1),
  ORCH-040 (uid/gid/HOME группа), ORCH-058 (staging ≠ прод-порт), INV-4 (мерж только через
  PR-merge API) — инструкция обязана им следовать, а не противоречить.
