From 3a103a6e926a5169c53160ef6bf1cdb63687afb6 Mon Sep 17 00:00:00 2001 From: Slava Date: Wed, 10 Jun 2026 21:20:58 +0300 Subject: [PATCH 1/7] docs: init ORCH-102 business request --- docs/work-items/ORCH-102/00-business-request.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 docs/work-items/ORCH-102/00-business-request.md diff --git a/docs/work-items/ORCH-102/00-business-request.md b/docs/work-items/ORCH-102/00-business-request.md new file mode 100644 index 0000000..647658a --- /dev/null +++ b/docs/work-items/ORCH-102/00-business-request.md @@ -0,0 +1,7 @@ +# Business Request: ORCH-10a Lite-тираж: перенос орк+watchdog + полная инструкция донастройки окружения + +Work Item ID: ORCH-102 + +## Description + +TBD -- 2.49.1 From 30f1f33af10aafdb3e044ed42bed0de2b06e8561 Mon Sep 17 00:00:00 2001 From: claude-bot Date: Wed, 10 Jun 2026 21:32:17 +0300 Subject: [PATCH 2/7] analyst(ET): auto-commit from analyst run_id=608 --- docs/work-items/ORCH-102/01-brd.md | 211 ++++++++++++++ docs/work-items/ORCH-102/02-trz.md | 270 ++++++++++++++++++ .../ORCH-102/03-acceptance-criteria.md | 181 ++++++++++++ docs/work-items/ORCH-102/04-test-plan.yaml | 146 ++++++++++ 4 files changed, 808 insertions(+) create mode 100644 docs/work-items/ORCH-102/01-brd.md create mode 100644 docs/work-items/ORCH-102/02-trz.md create mode 100644 docs/work-items/ORCH-102/03-acceptance-criteria.md create mode 100644 docs/work-items/ORCH-102/04-test-plan.yaml diff --git a/docs/work-items/ORCH-102/01-brd.md b/docs/work-items/ORCH-102/01-brd.md new file mode 100644 index 0000000..90c7dee --- /dev/null +++ b/docs/work-items/ORCH-102/01-brd.md @@ -0,0 +1,211 @@ +--- +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-гейт, тест на отсутствие + секретоподобных значений. diff --git a/docs/work-items/ORCH-102/02-trz.md b/docs/work-items/ORCH-102/02-trz.md new file mode 100644 index 0000000..aeefcba --- /dev/null +++ b/docs/work-items/ORCH-102/02-trz.md @@ -0,0 +1,270 @@ +--- +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 `; конкретику источника + фиксирует Владелец (вне репо). + +--- + +## 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) — инструкция обязана им следовать, а не противоречить. diff --git a/docs/work-items/ORCH-102/03-acceptance-criteria.md b/docs/work-items/ORCH-102/03-acceptance-criteria.md new file mode 100644 index 0000000..624cda1 --- /dev/null +++ b/docs/work-items/ORCH-102/03-acceptance-criteria.md @@ -0,0 +1,181 @@ +--- +work_item: ORCH-102 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-10 +model_used: claude-opus-4-8 +--- + +# 03 — Критерии приёмки (Acceptance Criteria): ORCH-102 — ORCH-10a Lite-тираж + +Work Item: **ORCH-102** · Repo: **orchestrator** · Стадия: analysis + +Формат: каждый критерий имеет **PASS** (что должно быть истинно для приёмки) и **FAIL** +(что считается провалом). Любой машинный/ручной reviewer проверяет их буквально по файлам +репозитория. AC-1…AC-5 — дословно из бизнес-запроса (уточнены до проверяемости); +AC-6…AC-7 — детализация скоупа (анти-дрейф / инварианты). + +--- + +## AC-1 — `docs/deployment/LITE_SETUP.md`: полная пошаговая, без доп-вопросов + +**Условие:** инструкция существует и покрывает сквозной маршрут Lite-тиража; каждый шаг — +команда/проверка; человек, не видевший платформу, разворачивает по ней без доп-вопросов. +- **PASS:** + - файл `docs/deployment/LITE_SETUP.md` существует (путь — по исходу А-3; отклонение от пути + бизнес-запроса зафиксировано в ADR задачи); + - покрыты ВСЕ разделы нормативного перечня ТЗ §FR-1: рамка Lite/границы; предусловия хоста + (зависимости, uid/gid: `ORCH_RUN_UID/GID`, `ORCH_DOCKER_GID` через `getent group docker`, + владение `ORCH_HOST_REPOS_DIR`); перенос кода (чекаут `orchestrator`, без данных); + конфигурация (`.env` с нуля от `.env.example` + `gen_secrets.py`, обязательные ключи нового + хоста включая `ORCH_PROJECTS_JSON`); Plane (workspace/проект, точная модель статусов с + fail-closed `Confirm Deploy`/`STOP`, API-токен, webhook+HMAC `X-Plane-Signature` + каверза + Plane CE); Gitea (репо, токен со scope, per-repo webhook `X-Gitea-Signature`, один глобальный + секрет, норматив защиты `main` по исходу А-1); LLM (claude CLI: дистрибутив/node/аутентификация/ + `ORCH_CLAUDE_BIN`/модели ORCH-41); Telegram (бот трекера + отдельный watchdog-бот + + получение chat-id); запуск compose + health-чек (`/health`, `/queue`, `/metrics`); + регистрация проекта (`onboard_project.py` → `ORCH_PROJECTS_JSON` → управляемый рестарт); + smoke; stateless-проверка; траблшутинг (≥ 5 типовых отказов: симптом → диагностика → лечение); + - **каждый** нормативный шаг несёт исполняемую команду (fenced code block) И явную проверку + результата (маркер «Проверка:» / PASS-FAIL / ожидаемый вывод); + - копируемые команды generic: хост-специфика только плейсхолдерами `<...>`/`$ENV_VAR`; + боевых литералов (`mva154`, `duckdns`, `82.22.50.71`, реальные токены) в код-блоках нет; + - «без доп-вопросов» подтверждено операционально: приёмочный smoke-прогон по инструкции + выполнен на чистом контуре и зафиксирован (см. AC-4) + траблшутинг покрывает типовые отказы. +- **FAIL:** файла нет; ИЛИ отсутствует любой нормативный раздел FR-1; ИЛИ есть шаг без + команды/проверки («настройте webhook» без как-проверить); ИЛИ в копируемых командах боевые + URL/пути/секреты; ИЛИ инструкция отсылает за обязательным шагом во внешний (вне репо) источник. + +--- + +## AC-2 — Compose-подмножество: только орк+watchdog + +**Условие:** Lite разворачивает ровно `orchestrator`+`orchestrator-watchdog`; Plane/Gitea-контейнеров +нет; свойство зафиксировано и защищено. +- **PASS:** + - `docker compose config --services` (без активных профилей, пустой env) → + ровно `orchestrator` и `orchestrator-watchdog`; + - `orchestrator-staging` присутствует в файле строго за `profiles: [staging]` (дефолтный + `up -d` его не поднимает); + - в `docker-compose.yml` нет сервисов/образов Plane/Gitea (ни `plane*`, ни `gitea*`); + - LITE_SETUP.md документирует это свойство (что поднимется после `up -d` и почему staging + опционален — исход А-5); + - структурный тест compose-подмножества (TC-04) существует и зелёный; + - если по исходу А-2 введён отдельный lite-compose — он покрыт тем же тестом, а existing + `docker-compose.yml` не форкается без обоснования в ADR. +- **FAIL:** дефолтный запуск поднимает что-то кроме орк+watchdog; ИЛИ staging вне профиля; + ИЛИ в compose появился Plane/Gitea-сервис; ИЛИ свойство не задокументировано; ИЛИ тест + отсутствует/красный. + +--- + +## AC-3 — Stateless: чистая БД, ни одной нашей задачи/секрета + +**Условие:** инструкция предписывает чистый старт и не допускает переноса наших данных/секретов; +сама дока секретов не содержит. +- **PASS:** + - LITE_SETUP.md нормативно фиксирует: БД создаётся пустой при первом старте (`data/` чист, + переносить нечего); `.env`/`.env.staging`/`.env.watchdog` собираются с нуля; явная строка + «данные/задачи/секреты боевого хоста НЕ переносятся» (зеркало REPLICATION.md §5); + - секреты — только выпуск НОВЫХ: `gen_secrets.py` (webhook) + чек-лист внешних токенов + (ссылка на REPLICATION.md §3); ни один шаг не предписывает копирование боевого секрета; + - инструкция содержит проверку чистоты развёрнутого инстанса: первый `GET /queue` — нулевые + счётчики jobs, ни одной задачи (`ORCH-*`/`ET-*`) в системе; + - в самом доке и тестах задачи нет реальных секретоподобных значений (только плейсхолдеры); + security-гейт (ORCH-022, `17-security-report.md`) — `PASS`. +- **FAIL:** любой шаг предписывает/допускает перенос БД/задач/боевого `.env`/секрета; ИЛИ нет + нормативной stateless-строки; ИЛИ нет проверки чистоты; ИЛИ в доке обнаружен реальный + секрет/боевой токен; ИЛИ security-гейт `FAIL`. + +--- + +## AC-4 — Smoke на чистом окружении проходит + +**Условие:** smoke существует как воспроизводимая процедура/чек-лист и подтверждён прогоном. +- **PASS:** + - LITE_SETUP.md несёт smoke-раздел: чек-лист с явным PASS/FAIL на каждый шаг, построенный на + REPLICATION.md §4 (ссылка, без форка процедуры): конфиг резолвится → `/health` → + `/queue`+`/metrics` → тестовый проект (`onboard_project.py plan/apply/verify`) → тестовая + задача → «конвейер доехал» (минимум: `analysis` отработала, артефакты `01–04` в ветке); + - итог процедуры — однозначный вердикт (все шаги PASS ⇒ тираж PASS); + - приёмочный прогон выполнен на чистом контуре — минимум staging-песочница + (`ORCH_STAGING_PORT`, изолированная БД `./data/staging`) + одноразовый sandbox-проект + (прецедент ORCH-101 AC-3 / ONBOARDING.md §5.2) — и зафиксирован в артефактах задачи + (`13-test-report.md` и/или `15-staging-log.md`: дата, контур, шаги, вердикт); + - процедура нигде не требует боевых данных/секретов (stateless, согласовано с AC-3). +- **FAIL:** smoke-раздела нет; ИЛИ шаги без явных PASS/FAIL («посмотреть, что всё ок»); ИЛИ + процедура форкает REPLICATION.md §4 с расхождениями; ИЛИ заявленный прогон не зафиксирован в + артефактах; ИЛИ прогон провален и не разобран. + +--- + +## AC-5 — pytest зелёный; CHANGELOG; перекрёстные доки + +**Условие:** регресс чист, документация согласована (правила агентов №2/№6). +- **PASS:** + - полный `pytest tests/ -q` зелёный (включая новые структурные тесты задачи и существующие + `test_no_host_hardcodes` / `test_replication_smoke` / `test_infra_parametrization` / + `test_onboarding_*` — не ослаблены и не правлены под задачу без согласования); + - `CHANGELOG.md` содержит запись ORCH-102; + - `docs/operations/REPLICATION.md` §1: строка «Type A — Lite» обновлена (статус ✅/ссылка на + LITE_SETUP.md) — границы 10-common vs Lite vs Bundled остаются честными; + - `README.md`/`CLAUDE.md` обновлены, если фактический объём того требует (новая операторская + способность — Lite-тираж; README не выдаёт нерешённое за решённое и наоборот). +- **FAIL:** любой тест красный; ИЛИ нет записи в CHANGELOG; ИЛИ REPLICATION.md §1 продолжает + числить Lite «отдельной задачей» без ссылки; ИЛИ обзорные доки противоречат факту. + +--- + +## AC-6 — Канон не форкается; анти-дрейф защита + +**Условие:** инструкция — маршрутизатор поверх golden source'ов, её полнота защищена тестом. +- **PASS:** + - канонические данные (22 статуса, карта env, формат вебхуков, онбординг, smoke) даны ссылкой + на golden source (`ONBOARDING.md` §1 / `REPLICATION.md` §2–§4 / `SETUP_WEBHOOKS.md`); при + дублировании таблицы — анти-дрейф тест сверяет дубль с источником истины (импорт из + `src/plane_sync.py` / парсинг `.env.example`), не строковой копией; + - `tests/test_lite_setup_doc.py` существует и проверяет минимум: наличие дока; обязательные + кирпичи (ТЗ FR-6.1); согласованность упомянутых env-ключей с `.env.example` (FR-6.2); + compose-подмножество (FR-6.3); stateless-норматив и отсутствие боевых литералов/секретов в + код-блоках (FR-6.4); перекрёстность REPLICATION→LITE_SETUP и запись CHANGELOG (FR-6.5); + - тест детерминирован (повторные прогоны стабильны, без сети/LLM). +- **FAIL:** таблица статусов/env скопирована без анти-дрейф сверки; ИЛИ тест отсутствует/не + ловит исчезновение обязательного раздела/кирпича; ИЛИ упомянутый в доке env-ключ отсутствует + в `.env.example`; ИЛИ тест флапает/ходит в сеть. + +--- + +## AC-7 — Self-hosting безопасность и неизменность конвейера + +**Условие:** задача не дестабилизирует общий прод и не меняет рантайм. +- **PASS:** + - дифф задачи — `docs/**`, `tests/**`, `CHANGELOG.md` (+ согласованные обзорные доки, + + `.env.watchdog.example` при исходе А-4); `src/**` не изменён — либо каждое отклонение + обосновано в ADR задачи; + - `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict ключи / схема БД — + без изменений; + - прод-контейнер `orchestrator` в рамках задачи не перезапускается; выкат — только штатным + конвейером (deploy-staging 8501 → ручной Confirm Deploy); + - инструкция не противоречит инвариантам платформы: ADR D10 ORCH-009 (без branch protection), + C-1 ORCH-100 (watchdog-бот ≠ бот орка), ORCH-040 (uid/gid/HOME группа), ORCH-058 + (staging-порт ≠ прод-порт), INV-4 (мерж только через PR-merge API), конвенции тиража + REPLICATION.md §1 (репо `orchestrator`, имена сервисов). +- **FAIL:** немотивированные правки `src/**`/compose/Dockerfile; ИЛИ дифф трогает машину + стадий/QG/вердикты/схему БД; ИЛИ рестарт прода вне штатного деплой-пути; ИЛИ шаг инструкции + предписывает запрещённое инвариантами (включить branch protection, переиспользовать токен орка + для watchdog, скопировать боевой секрет и т.п.). + +--- + +## Сводная матрица AC ↔ BR/FR + +| AC | Покрывает | +|----|-----------| +| AC-1 | BR-1, BR-2 / FR-1, FR-4, NFR-6 | +| AC-2 | BR-3 / FR-2 | +| AC-3 | BR-4 / FR-3, NFR-3 | +| AC-4 | BR-5 / FR-5 | +| AC-5 | BR-7 / FR-7, NFR-2 | +| AC-6 | BR-6, BR-8 / FR-6, NFR-4, NFR-5 | +| AC-7 | NFR-1, NFR-2 / §7 ТЗ (инварианты) | diff --git a/docs/work-items/ORCH-102/04-test-plan.yaml b/docs/work-items/ORCH-102/04-test-plan.yaml new file mode 100644 index 0000000..ed787a8 --- /dev/null +++ b/docs/work-items/ORCH-102/04-test-plan.yaml @@ -0,0 +1,146 @@ +work_item: ORCH-102 +stage: analysis +author_agent: analyst +status: ready-for-review +created_at: 2026-06-10 +model_used: claude-opus-4-8 +title: "ORCH-10a Lite-тираж: инструкция LITE_SETUP + compose-подмножество — план тестов" +framework: pytest +scope: > + Покрывается: существование и полнота docs/deployment/LITE_SETUP.md (нормативные + разделы FR-1, форма «команда+проверка», generic-команды без боевых литералов), + согласованность упомянутых env-ключей с каноном .env.example, структурная + фиксация compose-подмножества (ровно орк+watchdog, staging за профилем, без + Plane/Gitea-сервисов), stateless-нормативы и секрет-гигиена дока, перекрёстные + ссылки (REPLICATION.md §1, CHANGELOG), воспроизводимый smoke-чек-лист и его + приёмочный прогон на чистом контуре, полный регресс. Вне покрытия: реальный + e2e-тираж на новом железе заказчика (заменён прогоном на staging-песочнице — + прецедент ORCH-101 AC-3), установка Plane/Gitea как таковых, задача 10b + (Bundled), перенос данных (stateless по решению 10.06). +notes: > + Задача docs-first: ожидаемый дифф — docs/** + tests/** + CHANGELOG.md + (+ .env.watchdog.example при исходе А-4); src/** не меняется. Имя нового + тест-модуля tests/test_lite_setup_doc.py — предложение analyst; developer может + переименовать/разбить, сохранив покрытие TC (образец структурных док-тестов — + tests/test_replication_smoke.py). Тесты детерминированы, без сети/LLM. + Полный регресс tests/ обязан остаться зелёным; STAGE_TRANSITIONS/QG_CHECKS/ + check_*/machine-verdict не меняются — новые тесты входят в существующие гейты + (check_ci_green / merge-gate re-test / coverage-гейт ORCH-027) автоматически. + TC-09 — процедурная приёмка AC-4: прогон фиксируется tester'ом в + 13-test-report.md / 15-staging-log.md, а не автоматизируется в pytest. + +tests: + - id: TC-01 + type: unit + description: > + LITE_SETUP.md существует по канонному пути (docs/deployment/, исход А-3 — + синхронизировать с ADR) и несёт ВСЕ нормативные разделы FR-1: рамка/границы + Lite, предусловия хоста (зависимости, uid/gid, getent group docker), перенос + кода, конфигурация (.env с нуля + gen_secrets.py + ORCH_PROJECTS_JSON), + Plane (статусы/токен/webhook+HMAC), Gitea (репо/токен/webhook), LLM + (claude CLI), Telegram (трекер + watchdog-бот + chat-id), запуск+health-чек, + регистрация проекта, smoke, stateless-проверка, траблшутинг (AC-1 / FR-1). + module: tests/test_lite_setup_doc.py + expected: PASS + + - id: TC-02 + type: unit + description: > + Форма «каждый шаг — команда/проверка»: нормативные разделы содержат fenced + code blocks с исполняемыми командами и явные маркеры проверки + (PASS/FAIL/«Проверка:»); ключевые кирпичи присутствуют: docker compose, + /health, /queue, /metrics, gen_secrets.py, onboard_project.py, + X-Plane-Signature, X-Gitea-Signature (AC-1 / FR-1, NFR-6). + module: tests/test_lite_setup_doc.py + expected: PASS + + - id: TC-03 + type: unit + description: > + Согласованность env-канона: каждый ключ ORCH_*/WATCHDOG_*, упомянутый в + LITE_SETUP.md, существует в .env.example; обязательный набор нового хоста + упомянут явно (ORCH_PROJECTS_JSON, ORCH_PLANE_WEBHOOK_SECRET, + ORCH_GITEA_WEBHOOK_SECRET, ORCH_PLANE_API_TOKEN, ORCH_GITEA_TOKEN, + ORCH_TELEGRAM_BOT_TOKEN, ORCH_TELEGRAM_CHAT_ID, WATCHDOG_TG_BOT_TOKEN, + WATCHDOG_TG_CHAT_ID) (AC-1, AC-6 / FR-1.4, FR-6.2). + module: tests/test_lite_setup_doc.py + expected: PASS + + - id: TC-04 + type: unit + description: > + Compose-подмножество (AC-2): docker-compose.yml парсится; множество сервисов + ровно {orchestrator, orchestrator-watchdog, orchestrator-staging}; + orchestrator-staging строго за profiles: [staging] (дефолтный up -d поднимает + ровно орк+watchdog); ни одного сервиса/образа plane*/gitea*; LITE_SETUP.md + документирует состав дефолтного запуска (AC-2 / FR-2). + module: tests/test_lite_setup_doc.py + expected: PASS + + - id: TC-05 + type: unit + description: > + Stateless и секрет-гигиена (AC-3): док несёт нормативную строку «боевые + данные/задачи/секреты не копируются» и предписывает чистую БД + выпуск + новых секретов (gen_secrets.py); проверка чистоты инстанса (первый GET + /queue без задач) описана; в копируемых код-блоках нет боевых литералов + (mva154, duckdns, 82.22.50.71) и секретоподобных значений — только + плейсхолдеры <...>/$ENV_VAR (AC-3 / FR-3, NFR-3). + module: tests/test_lite_setup_doc.py + expected: PASS + + - id: TC-06 + type: unit + description: > + Канон не форкается (AC-6): раздел Plane-статусов ссылается на golden source + (ONBOARDING.md §1 / onboard_project.py) и явно упоминает fail-closed имена + Confirm Deploy и STOP; при наличии дубля таблицы статусов в доке — дубль + сверяется с plane_sync._PLANE_NAME_TO_KEY импортом (22 имени, нулевой + дрейф); карта env и smoke даны ссылкой на REPLICATION.md (AC-6 / FR-4, + NFR-4). + module: tests/test_lite_setup_doc.py + expected: PASS + + - id: TC-07 + type: unit + description: > + Раздел Gitea соответствует инвариантам платформы: события + push/pull_request/status, ОДИН глобальный webhook-секрет на все репо, + и норматив защиты main согласован с исходом А-1 ADR задачи (канон: branch + protection НЕ включать — ADR D10 ORCH-009; инструкция не предписывает + запрещённого) (AC-1, AC-7 / FR-1.6, §3.8 А-1). + module: tests/test_lite_setup_doc.py + expected: PASS + + - id: TC-08 + type: unit + description: > + Перекрёстная документация (AC-5): REPLICATION.md §1 (границы 10-common vs + Lite vs Bundled) ссылается на LITE_SETUP.md / отмечает Lite реализованным; + CHANGELOG.md содержит запись ORCH-102 (AC-5 / FR-7). + module: tests/test_lite_setup_doc.py + expected: PASS + + - id: TC-09 + type: integration + description: > + Приёмочный smoke-прогон по LITE_SETUP.md на чистом контуре (минимум: + staging-песочница ORCH_STAGING_PORT с изолированной БД ./data/staging + + одноразовый sandbox-проект; прецедент ORCH-101 AC-3): чек-лист REPLICATION + §4 шаги 0–5 — конфиг резолвится, /health 200, /queue+/metrics штатны, + onboard verify зелёный, тестовая задача дошла до артефактов 01–04; вердикт + и контур зафиксированы в 13-test-report.md / 15-staging-log.md. Процедурная + приёмка (исполняет tester по чек-листу), не pytest-модуль (AC-4 / FR-5). + module: tests/manual/lite-smoke-checklist (процедура; протокол в 13/15) + expected: PASS + + - id: TC-10 + type: integration + description: > + Полный регресс: pytest tests/ -q зелёный; существующие структурные тесты + (test_no_host_hardcodes, test_replication_smoke, test_infra_parametrization, + test_onboarding_*) не ослаблены/не правлены под задачу; дифф не трогает + src/** (или каждое отклонение обосновано ADR), STAGE_TRANSITIONS/QG_CHECKS/ + machine-verdict/схему БД (AC-5, AC-7 / NFR-2). + module: tests/ + expected: PASS -- 2.49.1 From 443ddc6b6f39a0e8705ebbd7f7032e32ef21470e Mon Sep 17 00:00:00 2001 From: claude-bot Date: Wed, 10 Jun 2026 22:02:49 +0300 Subject: [PATCH 3/7] architect(ET): auto-commit from architect run_id=609 --- docs/architecture/README.md | 15 + docs/architecture/adr/README.md | 4 +- .../adr/adr-0037-lite-replication-canon.md | 96 ++++++ .../06-adr/ADR-001-lite-setup-doc-canon.md | 298 ++++++++++++++++++ docs/work-items/ORCH-102/10-tech-risks.md | 40 +++ 5 files changed, 452 insertions(+), 1 deletion(-) create mode 100644 docs/architecture/adr/adr-0037-lite-replication-canon.md create mode 100644 docs/work-items/ORCH-102/06-adr/ADR-001-lite-setup-doc-canon.md create mode 100644 docs/work-items/ORCH-102/10-tech-risks.md diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 070859d..7212b1c 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -195,6 +195,21 @@ env/конфиг; конвейер (`STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/ma `docs/work-items/ORCH-101/06-adr/ADR-001-host-parametrization-secrets-smoke.md` (D1…D10), `docs/work-items/ORCH-101/07-infra-requirements.md`, `10-tech-risks.md`. +**Type A — Lite (ORCH-102 — design).** Поверх 10-common вводится канон Lite-тиража: новый +docs-раздел `docs/deployment/` (витрина тиража, читатель — внешний оператор) с golden source +`docs/deployment/LITE_SETUP.md` — сквозной маршрут «голый хост → работающий конвейер» из 13 +нормативных разделов (предусловия → код → конфиг/секреты → Plane → Gitea → LLM → Telegram → +запуск → онбординг проекта → smoke → stateless-проверка → траблшутинг), каждый шаг = +fenced-команда + явная проверка (PASS/FAIL), хост-специфика — только плейсхолдеры. Compose не +форкается: `docker-compose.yml` сам является Lite-подмножеством (дефолтный `up -d` поднимает +ровно `orchestrator`+`orchestrator-watchdog`; staging — за профилем, в Lite опционален). Канон +watchdog-конфига — новый `.env.watchdog.example` (key-set = блоку `WATCHDOG_*` `.env.example`; +sidecar читает только `.env.watchdog`; C-1 ORCH-100 — отдельный бот). Норматив тиражной +инсталляции Gitea: branch protection на `main` НЕ включать (D10 ORCH-009, защита merge-актора). +Анти-дрейф — структурный `tests/test_lite_setup_doc.py`. Рантайм/конвейер — байт-в-байт +(docs+tests). Подробнее: [adr-0037](adr/adr-0037-lite-replication-canon.md), детально — +`docs/work-items/ORCH-102/06-adr/ADR-001-lite-setup-doc-canon.md`. + ## Конвейер и Quality Gates ``` diff --git a/docs/architecture/adr/README.md b/docs/architecture/adr/README.md index 1a90f85..b9b65f4 100644 --- a/docs/architecture/adr/README.md +++ b/docs/architecture/adr/README.md @@ -41,11 +41,13 @@ Per-work-item решения живут в `docs/work-items//06-adr/ADR-NNN- | adr-0033 | Sidecar-watchdog F1b — мозг мониторинга в отдельном контейнере | proposed | 2026-06-10 | ORCH-100 | | adr-0034 | Машинный журнал уроков — таблица `lessons` + observer-leaf | proposed | 2026-06-10 | ORCH-098 | | adr-0035 | Turnkey-онбординг проектов — kit + операторский CLI + runbook | proposed | 2026-06-10 | ORCH-009 | +| adr-0036 | Фундамент тиража платформы — параметризация хоста, секреты, smoke (10-common) | proposed | 2026-06-10 | ORCH-101 | +| adr-0037 | Канон Lite-тиража — `docs/deployment/LITE_SETUP.md` + `.env.watchdog.example` | proposed | 2026-06-10 | ORCH-102 | > ⚠️ Историческая коллизия: номер `0007` занят двумя файлами — > `adr-0007-reconciler.md` (ORCH-053) и `adr-0007-executable-self-deploy.md` > (ORCH-036). Оба accepted; для новых сквозных ADR использовать следующий -> свободный номер (текущий максимум — `0035`). +> свободный номер (текущий максимум — `0037`). > adr-0014 **amends** adr-0013 (меняет критерий merge-verify на «SHA-в-main»). > adr-0016 **amends** adr-0013/0014 (гарантирует открытый код-PR перед merge_pr, ORCH-082). > adr-0020 реализует машинный слой к adr-0019 (ORCH-52b→52c). diff --git a/docs/architecture/adr/adr-0037-lite-replication-canon.md b/docs/architecture/adr/adr-0037-lite-replication-canon.md new file mode 100644 index 0000000..82114a7 --- /dev/null +++ b/docs/architecture/adr/adr-0037-lite-replication-canon.md @@ -0,0 +1,96 @@ +--- +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`. diff --git a/docs/work-items/ORCH-102/06-adr/ADR-001-lite-setup-doc-canon.md b/docs/work-items/ORCH-102/06-adr/ADR-001-lite-setup-doc-canon.md new file mode 100644 index 0000000..275eca6 --- /dev/null +++ b/docs/work-items/ORCH-102/06-adr/ADR-001-lite-setup-doc-canon.md @@ -0,0 +1,298 @@ +--- +work_item: ORCH-102 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-10 +model_used: claude-opus-4-8 +--- + +# ADR-001: Канон Lite-тиража — `docs/deployment/LITE_SETUP.md`, исходы А-1…А-6, анти-дрейф контур + +Work Item: **ORCH-102** — ORCH-10a Lite-тираж: перенос орк+watchdog + полная инструкция донастройки окружения +Стадия: **architecture** +Сквозная регистрация: **`docs/architecture/adr/adr-0037-lite-replication-canon.md`** +(новый docs-раздел `docs/deployment/`, новый канонический example-файл и нормативы тиражной +инсталляции — кросс-каттинг для всех будущих задач эпика ORCH-10 и для агентов, меняющих шаги тиража). + +## Статус +Proposed + +## Контекст + +Эпик ORCH-10 (D5 «Масштаб»), тип **A — Lite**: заказчик-тестер разворачивает на своей инфре +ТОЛЬКО орк+watchdog, окружение (Plane/Gitea/LLM/Telegram) донастраивает сам по инструкции. +Решения Владельца 10.06 (BRD §1.4): оба типа тиража stateless (D-2), главный продукт ORCH-102 — +**инструкция** `docs/deployment/LITE_SETUP.md` (D-4). + +Факты, сверенные с кодом/репо на ветке задачи: + +- **Фундамент 10-common (ORCH-101) в `main`** (adr-0036): хост-значения параметризованы + (`${VAR:-default}`, «дефолт = боевое значение»), секреты выпускаются заново + (`scripts/gen_secrets.py`), smoke с PASS/FAIL — `docs/operations/REPLICATION.md` §4, + анти-регресс `tests/test_no_host_hardcodes.py` (центральный список `FORBIDDEN` + хелпер + `find_violations`). Технически платформа разворачивается без правки кода; операционно + единого маршрута для заказчика нет (знания в 4 operations-доках, писанных для НАШЕГО хоста). +- **`docker-compose.yml` уже является Lite-подмножеством:** ровно 3 сервиса — + `orchestrator`, `orchestrator-watchdog`, `orchestrator-staging`; staging строго за + `profiles: [staging]`; сервисов/образов Plane/Gitea нет. Дефолтный `docker compose up -d` + поднимает ровно орк+watchdog. Свойство нигде не зафиксировано и ничем не защищено. +- **Гэп канона watchdog-конфига:** compose читает `.env.watchdog` + (`env_file: {path: .env.watchdog, required: false}`), но example-файла нет (есть только + `.env.example` / `.env.staging.example`). Ключи `WATCHDOG_*` (19 шт., дефолты = + `watchdog/config.py`) задокументированы внутри `.env.example` — однако sidecar-контейнер + читает ТОЛЬКО `.env.watchdog`: ключ, положенный оператором в `.env`, для watchdog **инертен** + (в `.env` его видит лишь контейнер орка через его `env_file`). Двусмысленность файла-носителя — + реальная ловушка первичной настройки. +- **«Pre-receive хуки» из бизнес-запроса конфликтуют с действующим нормативом:** ORCH-009 + ADR-001 **D10** — branch protection на `main` НЕ включать (required-approvals/status-checks → + 405/409-класс отказов `merge_pr` → ложные HOLD, класс инцидента ORCH-063); merge-актор работает + только через Gitea PR-merge API (INV-4, `src/merge_gate.py`). Pre-receive хуков в платформе нет; + защита `main` — конвенция (агенты не пушат `main`) + скоуп токенов. +- **Парсер YAML доступен тестам** (`yaml.safe_load` уже используется в + `tests/test_infra_parametrization.py::_compose_services`) — структурный тест + compose-подмножества не требует новых зависимостей. +- Прецедент приёмки smoke без нового железа: ORCH-101 AC-3 — staging-песочница + (`ORCH_STAGING_PORT`=8501, изолированная БД `./data/staging`) + sandbox-проект + (ONBOARDING.md §5, журнал smoke-прогонов). + +Задача — **docs+tests** (паттерн ORCH-077/092): `src/**`, `docker-compose.yml`, `Dockerfile`, +`scripts/**` читаются как источник истины и НЕ меняются; конвейер +(`STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict/схема БД) — байт-в-байт. + +## Решение + +### Сводка + +Создаётся новый docs-раздел **`docs/deployment/`** (витрина тиража) с golden source +**`docs/deployment/LITE_SETUP.md`** — сквозной маршрут «голый хост → работающий конвейер» из 13 +нормативных разделов (D2), собирающий кирпичи 10-common ссылками, без форка канона. Compose не +форкается (D4); канон watchdog-конфига закрывается новым **`.env.watchdog.example`** (D5); +раздел Gitea фиксирует действующий норматив D10 — branch protection НЕ включать, pre-receive не +вводить (D3). Полнота/гигиена дока и compose-подмножество защищаются структурным +`tests/test_lite_setup_doc.py` (D8). Рантайм не трогается; исходы всех вопросов ТЗ §3.8 — ниже. + +### D1 (исход А-3) — Размещение: новый раздел `docs/deployment/`, путь бизнес-запроса подтверждён + +**Решение: `docs/deployment/LITE_SETUP.md`, как зафиксировано Владельцем (D-4).** Семантика +разделов: `docs/deployment/` — «как развернуть платформу У СЕБЯ» (читатель — внешний +оператор/заказчик, платформу видит впервые); `docs/operations/` — «как эксплуатировать НАШ прод» +(читатель — оператор текущего хоста). `REPLICATION.md` остаётся в `docs/operations/` — это +runbook фундамента 10-common, исторический якорь ORCH-101, к пути прибит +`tests/test_replication_smoke.py`; перенос дал бы правку чужого артефакта без выгоды. +Перекрёстные ссылки обе стороны: REPLICATION.md §1 (строка Type A — Lite → ✅ ORCH-102 + ссылка +на LITE_SETUP.md) и LITE_SETUP.md §1 (границы — ссылкой на REPLICATION.md §1). INFRA.md получает +ссылку на deployment-раздел (по фактическому объёму, FR-7). + +Привязка: FR-1, FR-7, AC-1, AC-5. + +### D2 (FR-1) — Нормативная структура LITE_SETUP.md: 13 разделов, форма «команда + проверка» + +**Решение: фиксированная нумерация `## N. <Название>`, порядок = маршрут оператора** (состав — +обязательный минимум FR-1; анти-дрейф тест ассертит наличие и порядок заголовков): + +| § | Раздел | Ключевое содержимое (норматив) | +|---|--------|--------------------------------| +| 1 | Рамка Lite | что разворачиваем (орк+watchdog); что заказчик ставит сам; границы vs 10-common/Bundled — ссылка REPLICATION.md §1; платформенные конвенции (репо `orchestrator`, имена сервисов, контейнерный layout — не менять) | +| 2 | Предусловия хоста | контур: Linux x86_64, Docker Engine + Compose v2, git, python3, node + дистрибутив claude-code; `ORCH_RUN_UID/GID` = uid владельца `ORCH_HOST_REPOS_DIR` (ORCH-040), `ORCH_DOCKER_GID` ← `getent group docker`; ssh (`ORCH_HOST_SSH_DIR`); свободные порты 8500/8501; **каждое предусловие — команда проверки** | +| 3 | Перенос кода | `git clone ` в `ORCH_DEPLOY_HOST_REPO_PATH` (D7); НИКАКИХ данных/БД/`.env` с боевого хоста; watchdog отдельно не переносится (код в `watchdog/` того же репо) | +| 4 | Конфигурация | `.env` с нуля от `.env.example` (канон); `python3 scripts/gen_secrets.py [--write]`; карта env — ссылка REPLICATION.md §2; явный список обязательных ключей нового хоста (вкл. `ORCH_PROJECTS_JSON`); `.env.watchdog` от `.env.watchdog.example` (D5); когерентность портов `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-токен + проверка `curl`; webhook+HMAC: URL `…/webhook/plane`, `X-Plane-Signature`, каверза Plane CE — оба пути (UI и SQL), generic-команды по образцу SETUP_WEBHOOKS.md с плейсхолдерами | +| 6 | Подключение Gitea | репо (`onboard_project.py` или вручную); токен scope `repo`,`admin:repo_hook` + проверка; per-repo webhook (`push`/`pull_request`/`status`, `X-Gitea-Signature`, ОДИН глобальный секрет); **норматив D3: branch protection НЕ включать** | +| 7 | LLM (claude CLI) | дистрибутив claude-code и node на хосте = источники маунтов (`ORCH_HOST_CLAUDE_CODE_DIR`/`ORCH_HOST_NODE_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 → `ORCH_TELEGRAM_BOT_TOKEN`), `chat_id` через `getUpdates`, проверка `getMe`; **отдельный** watchdog-бот → `.env.watchdog` (C-1 ORCH-100: токен орка переиспользовать ЗАПРЕЩЕНО) | +| 9 | Запуск | `docker compose config` → `up -d --build` → ровно `orchestrator`+`orchestrator-watchdog` (D4); health-чек `GET /health` → 200 `"status":"ok"`, `/queue`+`/metrics` → штатный JSON (`schema_version: 1`); **вилка staging (D6)** | +| 10 | Регистрация проекта | `onboard_project.py plan → apply → verify` (статусы+лейблы `autoApprove`/`autoDeploy`/`Bug`, репо+webhook, kit, merged `ORCH_PROJECTS_JSON`) → строка в `.env` → управляемый рестарт → `/health`+`/queue`; маршрут — ссылка ONBOARDING.md, в доке — последовательность команд Lite | +| 11 | Smoke | чек-лист REPLICATION.md §4 (шаги 0–5, опционально 6 до `done`) ссылкой + Lite-предусловия; критерий «конвейер доехал»: задача в БД → analyst-job в `/queue` → артефакты `01–04` в ветке | +| 12 | Stateless-проверка | первый старт = пустая БД (`data/` чист); `GET /queue` — нулевые счётчики, ни одной задачи `ORCH-*`/`ET-*`; нормативная строка «данные/задачи/секреты боевого хоста НЕ переносятся» | +| 13 | Траблшутинг | ≥ 5 отказов, каждый «симптом → команда диагностики → лечение»: webhook 401/HMAC mismatch; задача не появилась (реестр/`ORCH_PROJECTS_JSON`/webhook); claude CLI не найден/не аутентифицирован; docker.sock permission denied (`ORCH_DOCKER_GID`); права `/repos` (uid mismatch, ORCH-040/057); Telegram молчит | + +**Форма (нормативно, NFR-6/BR-1):** (а) каждый нормативный шаг = fenced-команда + явная проверка +(маркер «Проверка:» / PASS/FAIL / ожидаемый вывод); (б) хост-специфика в fenced-блоках — ТОЛЬКО +плейсхолдеры `<...>`/`$ENV_VAR`; боевые литералы (`mva154`, `duckdns`, `82.22.50.71`, реальные +токены) запрещены; дефолты хост-переменных НЕ копируются в док — ссылка на карту +REPLICATION.md §2 (иначе fenced-скан D8 и форк канона); (в) язык — русский; (г) футер дока несёт +норматив сопровождения (NFR-5: меняешь шаги тиража → обнови LITE_SETUP.md в том же PR, +правило агентов №2). + +Привязка: FR-1, FR-3, FR-4, AC-1, AC-3. + +### D3 (исход А-1) — Раздел Gitea: канон D10, pre-receive НЕ вводить + +**Решение: раздел Gitea фиксирует канон платформы — репо + токен (scope `repo`, +`admin:repo_hook`) + per-repo webhook + нормативная рамка «branch protection на `main` НЕ +включать».** Формулировка бизнес-запроса «pre-receive хуки» трактуется по намерению («защита +`main`») и закрывается действующей моделью: мерж — только через Gitea PR-merge API под токеном +орка (INV-4, `src/merge_gate.py`); агенты не пушат `main` (конвенция + скоуп токенов). +Pre-receive хуки НЕ вводятся: это server-side механизм инсталляции Gitea заказчика, платформа +его не несёт и не проверяет; required-approvals/status-checks дали бы 405/409-класс отказов +`merge_pr` → ложные HOLD (ORCH-009 ADR-001 D10, инцидент ORCH-063). В §13 (траблшутинг) — +симптом «PR не мержится / HOLD» с первой проверкой «не включена ли branch protection». +Пересмотр — только отдельным ADR с анализом совместимости с merge-актором (ORCH-093/INV-4). + +Привязка: BRD §1.3/§6, FR-1 п.6, AC-7. + +### D4 (исход А-2) — Compose: существующий файл, без lite-форка; свойство держит тест + +**Решение: `docker-compose.yml` НЕ форкается** — он уже является Lite-подмножеством (факт из +контекста). Отдельный `docker-compose.lite.yml` отвергнут: второй файл = вторая правда = +поверхность дрейфа (зеркало решения D9 ORCH-101 «без скрипта-обвязки»). Свойство фиксируется +в LITE_SETUP.md §9 и защищается тестом (D8, TC-04) через `yaml.safe_load` (паттерн +`tests/test_infra_parametrization.py::_compose_services`): + +- `set(services) == {"orchestrator", "orchestrator-watchdog", "orchestrator-staging"}`; +- `services["orchestrator-staging"]["profiles"] == ["staging"]`; +- множество сервисов без `profiles` (= дефолтный `up -d`) — ровно + `{"orchestrator", "orchestrator-watchdog"}`; +- ни в имени сервиса, ни в `image:`/`container_name:` нет подстрок `plane`/`gitea` + (анти-появление молча). + +Привязка: FR-2, AC-2, BR-3. + +### D5 (исход А-4) — `.env.watchdog.example`: создать; key-set синхронизирован тестом + +**Решение: создать `.env.watchdog.example`** — третий канонический env-example +(симметрия `.env.example`/`.env.staging.example`), единственное разрешённое отклонение диффа от +docs+tests (предусмотрено ТЗ §2). Нормативное содержимое: + +- **полный набор ключей `WATCHDOG_*` — ровно тот же, что блок `WATCHDOG_*` в `.env.example`** + (key-set equality, 19 ключей; значения = дефолты канона/`watchdog/config.py`, + токены — пустые плейсхолдеры); +- шапка-комментарий: семантика файла-носителя — sidecar-контейнер читает ТОЛЬКО `.env.watchdog` + (compose `env_file: required: false`; отсутствие файла не ломает `up`; нет токена → fail-safe: + логи без отправки); **ключ `WATCHDOG_*` в `.env` для sidecar инертен**; +- норматив C-1 (ORCH-100): свой бот, независимый канал; токен орка переиспользовать запрещено; +- когерентность порта: `WATCHDOG_METRICS_URL` следует за `ORCH_DEPLOY_PROD_TARGET_PORT`; +- «не коммить реальный `.env.watchdog`» (зеркало шапки `.env.staging.example`). + +Анти-дрейф (D8, TC-02b): `keys(.env.watchdog.example) == {k ∈ keys(.env.example) | +k.startswith("WATCHDOG_")}` — появление нового ключа watchdog в каноне без обновления example +(и наоборот) ломает CI. Это дубль по необходимости, защищённый сверкой парсингом, не строкой +(NFR-4). LITE_SETUP.md §4/§8 предписывают `cp .env.watchdog.example .env.watchdog` + два токена. + +Привязка: FR-1 п.4/п.8, FR-6.2, AC-1, AC-7 (C-1). + +### D6 (исход А-5) — Staging-контур в Lite: опционален, явная вилка + +**Решение: базовый Lite-контур = prod-оркестратор (8500) + watchdog; `orchestrator-staging` +НЕ обязателен.** Staging нужен ТОЛЬКО если заказчик регистрирует проект `orchestrator` +(self-hosting развитие самой платформы у себя): стадия `deploy-staging` орка требует +песочницу 8501 (`.env.staging` от `.env.staging.example`, изолированная БД `./data/staging`, +guard ORCH-058: staging-порт ≠ прод-порт — fail-closed). Для целевого сценария «раздача на +тест» (заказчик гоняет СВОИ проекты) staging не участвует. В §9 — явная вилка двумя ветками +с командами; дефолтная ветка — без staging. + +Привязка: FR-1 п.9, AC-2 (staging за профилем), ТЗ §3.8 А-5. + +### D7 (исход А-6) — Источник кода: параметризованный шаг + +**Решение: шаг §3 — `git clone `** (плюс +опциональный `--branch <тег/срез>`). Конкретный канал дистрибуции (зеркало, доступ к нашему +Gitea, архив) — решение Владельца ВНЕ репо (коммерческая механика — анти-скоуп BRD §2.2); +док не хардкодит наш Gitea-URL (это же требует NFR-3/fenced-скан). Плейсхолдер +`` включён в перечень подстановок §3. + +Привязка: FR-1 п.3, BRD §6, ТЗ §3.8 А-6. + +### D8 (FR-6) — Анти-дрейф контур: `tests/test_lite_setup_doc.py` + +**Решение: один структурный модуль, детерминированный, без сети/LLM/subprocess** (образец — +`tests/test_replication_smoke.py`). Нормативные семейства проверок (точная нарезка по +тест-функциям — за developer, `04-test-plan.yaml`): + +| TC | Проверка | Механика | +|----|----------|----------| +| TC-01 | Док существует; 13 нормативных разделов D2 присутствуют **в заданном порядке** | regex по заголовкам `^## N\.` | +| TC-02 | Обязательные кирпичи FR-6.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/«Проверка» | подстроки | +| TC-02b | Key-sync `.env.watchdog.example` ⇄ блок `WATCHDOG_*` `.env.example` (D5) | парсинг строк `^KEY=` обоих файлов, равенство множеств | +| TC-03 | Каждый токен `\b(ORCH\|WATCHDOG)_[A-Z0-9_]+\b` из дока существует ключом в `.env.example` (канон 100% ключей, ORCH-101) | regex по доку + парсинг `.env.example` | +| TC-04 | Compose-подмножество (D4): 3 сервиса, staging за профилем, дефолтный up = орк+watchdog, нет `plane*`/`gitea*` | `yaml.safe_load` | +| TC-05 | Stateless/гигиена: нормативная строка «не перенос…» присутствует; **в fenced-блоках** нет литералов центрального списка `FORBIDDEN` (импорт из `tests/test_no_host_hardcodes.py`, НЕ копия — один источник истины) и секретоподобных значений (эвристика: hex/base64 ≥ 32 симв., не плейсхолдер) | выделение fenced-блоков + `find_violations`/эвристика | +| TC-06 | Перекрёстность: `REPLICATION.md` §1 ссылается на `LITE_SETUP.md`; `CHANGELOG.md` несёт `ORCH-102` | подстроки | + +Скоуп секрет/литерал-скана — **только fenced-блоки** (копируемое); проза дока дефолтов не +дублирует (D2-форма, п. б) — поэтому полнодокументный скан не нужен и не даёт ложно-красных. +Существующие тесты (`test_no_host_hardcodes`, `test_replication_smoke`, +`test_infra_parametrization`, `test_onboarding_*`) не ослабляются; новые тесты попадают в +существующие гейты (`check_ci_green`/`check_tests_passed`/merge-gate re-test/coverage ORCH-027) +автоматически — новый QG НЕ регистрируется (ТЗ §6). + +Привязка: FR-6, BR-8, AC-5, AC-6. + +### D9 — Границы изменения; что НЕ делается; 07/08 — N/A + +- **Дифф задачи:** `docs/**` (LITE_SETUP.md, правки REPLICATION §1/INFRA/README/CLAUDE.md по + объёму), `tests/test_lite_setup_doc.py`, `CHANGELOG.md`, `.env.watchdog.example` (D5). + **`src/**`, `docker-compose.yml`, `Dockerfile`, `scripts/**` — ноль изменений**; любое + отклонение — только новым ADR (AC-7). +- `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict ключи/схема БД — байт-в-байт; новых + эндпоинтов/флагов/kill-switch нет (выключать нечего — D-4: док и тесты). +- **`07-infra-requirements.md` / `08-data-requirements.md` — N/A:** топология не меняется (ни + контейнера, ни порта, ни маунта), схема БД не меняется (ТЗ §5). Инфра-предусловий нет: + приёмочный smoke-прогон (FR-5/AC-4) идёт на СУЩЕСТВУЮЩЕМ контуре — staging-песочница + `ORCH_STAGING_PORT`=8501 + одноразовый sandbox-проект (прецедент ORCH-101 AC-3 / + ONBOARDING.md §5); прогон на реальном новом хосте желателен, но не требование приёмки. +- **Self-hosting (NFR-1):** прод-контейнер не рестартится; выкат — штатный конвейер + (deploy-staging 8501 → ручной `Confirm Deploy`). Для enduro-trails изменение инертно. +- Эскалация: `arch:major-change` не требуется (нет новой стадии/компонента/смены БД); ТЗ + удовлетворимо без нарушения принципов — возврат в анализ не нужен. + +## Альтернативы + +- **Разместить инструкцию в `docs/operations/`** — отвергнуто: целевой читатель другой (внешний + оператор, не оператор нашего прода); путь `docs/deployment/LITE_SETUP.md` зафиксирован + Владельцем (D-4), отступать не от чего (D1). +- **Перенести REPLICATION.md в `docs/deployment/`** — отвергнуто: правка чужого артефакта и + путей `tests/test_replication_smoke.py` без выгоды; перекрёстных ссылок достаточно (D1). +- **Отдельный `docker-compose.lite.yml`** — отвергнуто: вторая правда о сервисах, дрейф- + поверхность; существующий файл уже = подмножество, тест дешевле форка (D4). +- **Pre-receive хуки / branch protection для «защиты `main`»** — отвергнуто: ломает PR-merge + API merge-актора (D10 ORCH-009, ложные HOLD); защита — конвенция + скоуп токенов + INV-4 (D3). +- **Без `.env.watchdog.example`, шаг «создай файл с двумя ключами» в доке** — отвергнуто: + двусмысленность файла-носителя остаётся (ключи канонизированы в `.env.example`, но там для + sidecar инертны); example-файл + key-sync тест дешевле и надёжнее прозы (D5). +- **Скопировать таблицу 22 статусов / карту env в LITE_SETUP.md** — отвергнуто: форк канона + (R-2); ссылки на golden source + явное упоминание только fail-closed имён + (`Confirm Deploy`/`STOP`) — достаточно (FR-4); дубль допустим только с тест-сверкой + парсингом/импортом (прецедент — TC-02b). +- **Полнодокументный секрет-скан (не только fenced)** — отвергнуто: ложно-красные на прозе + («не используйте mva154-значения»); норматив D2(б) выводит дефолты из дока, fenced-скан + покрывает всё копируемое (D8). + +## Последствия + +- **+** Закрывается Type A эпика ORCH-10: заказчик получает единый исполняемый маршрут + «голый хост → конвейер» без археологии по 4 докам; Type B (Bundled) строится поверх + (переиспользует §2–§8, §11–§13). +- **+** Compose-подмножество и полнота инструкции из «фактов» становятся CI-гарантиями + (TC-01…TC-06); ловушка файла-носителя watchdog-конфига закрыта каноном (D5). +- **+** Нулевой риск рантайма: docs+tests, конвейер байт-в-байт, kill-switch не нужен. +- **−** Новый golden source = новая обязанность сопровождения (шаги тиража меняются → + LITE_SETUP.md в том же PR; NFR-5) — митигировано футером-нормативом, правилом агентов №2 и + структурным тестом, который рвёт CI при дрейфе кирпичей. +- **−** Дубль ключей `WATCHDOG_*` в двух example-файлах — принят осознанно, защищён key-sync + тестом TC-02b (равенство множеств, не строк). +- **−** Приёмка «без доп-вопросов» на staging-песочнице ≠ прогон на реальном чужом хосте — + остаточный риск принят (прецедент ORCH-101 AC-3); зазор сужают чек-команды предусловий §2 и + траблшутинг §13. +- **Откат:** удалить `docs/deployment/`, `tests/test_lite_setup_doc.py`, + `.env.watchdog.example`, вернуть строку REPLICATION.md §1 — состояние 1:1, ни миграций, + ни состояния (ТЗ §7). + +## Ссылки + +- BRD: `docs/work-items/ORCH-102/01-brd.md` (решения Владельца D-1…D-5, факты §1.3) +- TRZ: `docs/work-items/ORCH-102/02-trz.md` (FR-1…FR-7, вопросы §3.8 А-1…А-6) +- Acceptance: `docs/work-items/ORCH-102/03-acceptance-criteria.md` (AC-1…AC-7) +- Риски: `docs/work-items/ORCH-102/10-tech-risks.md` +- Сквозной ADR: `docs/architecture/adr/adr-0037-lite-replication-canon.md` +- Сверено по коду/репо: `docker-compose.yml` (3 сервиса, `profiles: [staging]`, + `env_file: {path: .env.watchdog, required: false}`), `.env.example` (блок `WATCHDOG_*`, + 19 ключей), `watchdog/config.py` (дефолты), `tests/test_infra_parametrization.py` + (`yaml.safe_load`-паттерн), `tests/test_no_host_hardcodes.py` (`FORBIDDEN`, + `find_violations`), `tests/test_replication_smoke.py` (образец структурного теста дока), + `docs/operations/REPLICATION.md` §1–§5, `docs/operations/ONBOARDING.md` §1/§5, + `docs/operations/SETUP_WEBHOOKS.md` +- Инварианты соседних решений: ORCH-009 ADR-001 D10 (`docs/work-items/ORCH-009/06-adr/…`), + adr-0036 (ORCH-101, 10-common), adr-0035 (onboarding), adr-0033 (sidecar-watchdog, C-1 + ORCH-100), ORCH-040 (uid/gid/HOME), ORCH-058 (staging-порт guard), INV-4 (ORCH-093) diff --git a/docs/work-items/ORCH-102/10-tech-risks.md b/docs/work-items/ORCH-102/10-tech-risks.md new file mode 100644 index 0000000..14c1dc6 --- /dev/null +++ b/docs/work-items/ORCH-102/10-tech-risks.md @@ -0,0 +1,40 @@ +--- +work_item: ORCH-102 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-10 +model_used: claude-opus-4-8 +--- + +# 10 — Технические риски: ORCH-102 — ORCH-10a Lite-тираж (инструкция + анти-дрейф) + +Work Item: **ORCH-102** · Repo: **orchestrator** · Стадия: architecture + +> Информационный (гейтом не парсится). Перечисляет риски реализации и их митигейшн. +> Решения, на которые ссылаются митигейшны (D1…D9), — `06-adr/ADR-001-lite-setup-doc-canon.md`. + +## Реестр рисков + +| ID | Риск | Вер. | Влия. | Митигейшн | +|----|------|------|-------|-----------| +| TR-1 | **Дрейф инструкции**: платформа развивается, шаги LITE_SETUP.md тихо устаревают (новый env-ключ, изменённый маршрут онбординга) | Сред. | Сред. | Структурный `tests/test_lite_setup_doc.py` (D8: кирпичи, env-ключи ⊂ `.env.example`, compose-подмножество, перекрёстность) рвёт CI при дрейфе; футер-норматив NFR-5 + правило агентов №2 («шаги тиража → док в том же PR»); reviewer-ось обзорных доков (правило №6) | +| TR-2 | **Форк канона**: скопированная в док таблица статусов/env/вебхуков разъезжается с golden source | Низ. | Сред. | D2/FR-4: канон — только ссылками (ONBOARDING §1 / REPLICATION §2–§4 / SETUP_WEBHOOKS); в доке дублируются лишь fail-closed имена (`Confirm Deploy`/`STOP`) и списки обязательных ключей — оба под TC-02/TC-03; единственный структурный дубль (`WATCHDOG_*`) — под key-sync TC-02b | +| TR-3 | **«Без доп-вопросов» непроверяемо**: реальный заказчик найдёт пробел, который не увидел внутренний прогон | Сред. | Низ. | Операционализация BRD §6: каждый шаг = команда+проверка (TC-01/02), приёмочный smoke-прогон на чистом контуре фиксируется в `13-test-report.md`/`15-staging-log.md`, траблшутинг ≥5 отказов (§13). Остаточные пробелы лечатся правкой golden source штатной задачей | +| TR-4 | **Гетерогенность хостов заказчиков**: rootless docker, иной uid владельца репо, нет node/claude-code, arm64 | Сред. | Сред. | §2 «Предусловия» с явным поддерживаемым контуром (Linux x86_64, Docker+Compose v2, git, python3, node) и чек-командой на каждое предусловие (`getent group docker`, владение `ORCH_HOST_REPOS_DIR` = `ORCH_RUN_UID`); вне контура — вне гарантии Lite (BRD §6); §13 покрывает типовые отказы (docker.sock gid, uid mismatch ORCH-040/057) | +| TR-5 | **Заказчик включит branch protection / pre-receive на `main`** вопреки нормативу → ложные HOLD merge-актора на ЕГО инсталляции (класс ORCH-063) | Низ. | Выс. (у заказчика) | D3: явная нормативная рамка в §6 («НЕ включать», основание D10 ORCH-009/INV-4) + симптом в §13 («PR не мержится/HOLD → проверь protection»); для нашего прода риск нулевой (его Gitea не трогается) | +| TR-6 | **Утечка секрета/боевого литерала** через примеры дока или `.env.watchdog.example` | Низ. | Выс. | NFR-3: только плейсхолдеры; TC-05 — fenced-скан на `FORBIDDEN` (импорт из `test_no_host_hardcodes.py`, один источник истины) + эвристика секретоподобных значений; security-гейт ORCH-022 (`17-security-report.md`) обязан остаться PASS; D2(б): дефолты хост-переменных в док не копируются | +| TR-7 | **Хрупкость анти-дрейф теста**: ложно-красный CI от безобидной правки прозы → соблазн ослабить тест | Сред. | Низ. | D8: ассерты только на стабильное (заголовки `## N.`, подстроки-кирпичи, парсинг env-ключей, `yaml.safe_load`), запреты — только в fenced-блоках; никаких проверок прозы/формулировок; паттерн уже обкатан (`test_replication_smoke.py` стабилен) | +| TR-8 | **`.env.watchdog.example` разъезжается** с блоком `WATCHDOG_*` `.env.example` / дефолтами `watchdog/config.py` | Низ. | Низ. | TC-02b: равенство множеств ключей двух файлов; значения = дефолты канона (сверены с `watchdog/config.py` при ревью); полнота самого `.env.example` уже держится тестами ORCH-101 | +| TR-9 | **Приёмочный smoke на staging-песочнице ≠ голый чужой хост**: средовые эффекты нового железа (сеть, версии docker) не проверены | Сред. | Низ. | Принятый прецедент ORCH-101 AC-3 (без нового железа в контуре задачи; FR-5(г) — прогон на реальном хосте желателен, не блокер); зазор сужают чек-команды §2 и траблшутинг §13; первый реальный тираж — операторски сопровождаемый | + +## Сводный вывод + +Доминирующий класс — **документационный** (дрейф/полнота/гигиена), систематически закрытый +структурными тестами (TC-01…TC-06) и нормативом golden source; рантайм-рисков нет — дифф +docs+tests (+`.env.watchdog.example`), конвейер и `src/**` байт-в-байт (D9), kill-switch не +требуется. Самый тяжёлый по влиянию риск (TR-5) материализуется только на инсталляции +заказчика и купирован явным нормативом + траблшутингом. Эскалация `arch:major-change` не +требуется; возврат в анализ не нужен. **Остаточный риск для self-hosting прод-конвейера — +минимальный** (прод-контейнер не трогается; выкат — штатно через staging 8501 → +`Confirm Deploy`). -- 2.49.1 From 8351e91382a0cb4755ab449f748f9d68d7acdac7 Mon Sep 17 00:00:00 2001 From: claude-bot Date: Wed, 10 Jun 2026 22:18:48 +0300 Subject: [PATCH 4/7] =?UTF-8?q?docs(deployment):=20ORCH-10a=20Lite-=D1=82?= =?UTF-8?q?=D0=B8=D1=80=D0=B0=D0=B6=20=E2=80=94=20LITE=5FSETUP.md=20+=20?= =?UTF-8?q?=D0=BA=D0=B0=D0=BD=D0=BE=D0=BD=20watchdog-=D0=BA=D0=BE=D0=BD?= =?UTF-8?q?=D1=84=D0=B8=D0=B3=D0=B0=20+=20=D0=B0=D0=BD=D1=82=D0=B8-=D0=B4?= =?UTF-8?q?=D1=80=D0=B5=D0=B9=D1=84=20=D0=BA=D0=BE=D0=BD=D1=82=D1=83=D1=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Закрывает Type A эпика ORCH-10 (поверх 10-common ORCH-101). Docs+tests (паттерн ORCH-077/092): src/**, docker-compose.yml, Dockerfile, scripts/** — ноль изменений; конвейер (STAGE_TRANSITIONS/QG_CHECKS/check_*/machine-verdict/ схема БД) — байт-в-байт. - docs/deployment/LITE_SETUP.md (D1/D2): golden source Lite-тиража — 13 нормативных разделов в порядке маршрута оператора, каждый шаг = fenced-команда + явная «Проверка:»/PASS/FAIL, хост-специфика только плейсхолдерами; канон не форкается (статусы/env/вебхуки/smoke — ссылками на ONBOARDING §1 / REPLICATION §2–§4 / SETUP_WEBHOOKS; явно — только fail-closed Confirm Deploy/STOP и обязательные ключи нового хоста). - .env.watchdog.example (D5, исход А-4): третий канонический env-example; key-set = блок WATCHDOG_* .env.example (19 ключей, токены — пустые плейсхолдеры); закрывает ловушку файла-носителя (sidecar читает ТОЛЬКО .env.watchdog); C-1 ORCH-100 + когерентность порта в шапке; .env.watchdog добавлен в .gitignore (секрет-гигиена, зеркало .env.staging). - tests/test_lite_setup_doc.py (D8): 25 структурных тестов без сети/LLM/subprocess — 13 разделов в порядке D2, кирпичи FR-6.1, key-sync watchdog-канона, env-ключи ⊂ .env.example, compose-подмножество (ровно орк+watchdog по дефолту, staging за профилем, анти-появление plane*/gitea*), fenced-скан FORBIDDEN (импорт из test_no_host_hardcodes) + секрет-эвристика с негативным самочеком, «22 статуса» сверкой импорта plane_sync._PLANE_NAME_TO_KEY, перекрёстность. - Перекрёстные доки (FR-7): REPLICATION.md §1 (Type A — Lite → ✅ ORCH-102 + ссылка), README.md (способность Lite + docs/deployment/ в структуре), INFRA.md (.env.watchdog в секрет-нормативе + ссылка на deployment), CLAUDE.md (блок ORCH-102), CHANGELOG.md. Нормативы разделов: Gitea — branch protection на main НЕ включать (D3 / ADR D10 ORCH-009 / INV-4), pre-receive не вводится, ОДИН глобальный webhook-секрет; staging-вилка опциональна (D6); источник кода — параметризованный git clone (D7); stateless — данные/задачи/секреты боевого хоста НЕ переносятся (AC-3). Тесты: pytest tests/ -q — 1789 passed (полный регресс зелёный). Refs: ORCH-102 Co-Authored-By: Claude Opus 4.8 --- .env.watchdog.example | 42 +++ .gitignore | 2 + CHANGELOG.md | 6 + CLAUDE.md | 29 ++ README.md | 6 + docs/deployment/LITE_SETUP.md | 596 +++++++++++++++++++++++++++++++++ docs/operations/INFRA.md | 2 +- docs/operations/REPLICATION.md | 2 +- tests/test_lite_setup_doc.py | 428 +++++++++++++++++++++++ 9 files changed, 1111 insertions(+), 2 deletions(-) create mode 100644 .env.watchdog.example create mode 100644 docs/deployment/LITE_SETUP.md create mode 100644 tests/test_lite_setup_doc.py diff --git a/.env.watchdog.example b/.env.watchdog.example new file mode 100644 index 0000000..08fcfe0 --- /dev/null +++ b/.env.watchdog.example @@ -0,0 +1,42 @@ +# .env.watchdog — конфигурация sidecar-watchdog (контейнер orchestrator-watchdog). +# Канонический example (ORCH-102, ADR-001 D5; симметрия .env.example/.env.staging.example). +# +# ⚠️ СЕМАНТИКА ФАЙЛА-НОСИТЕЛЯ: sidecar-контейнер читает ТОЛЬКО этот файл +# (compose: env_file {path: .env.watchdog, required: false}). Ключ WATCHDOG_*, +# положенный в .env, для sidecar ИНЕРТЕН (его видит лишь контейнер орка). +# Отсутствие файла НЕ ломает `docker compose up` (required: false); нет токена → +# fail-safe: watchdog пишет алерты в логи, но не отправляет. +# +# Создание на хосте: cp .env.watchdog.example .env.watchdog → заполнить два токена. +# DO NOT COMMIT реальный .env.watchdog — этот файл только шаблон (зеркало +# .env.staging.example); реальные значения живут на хосте. +# +# Нормативы: +# * C-1 (ORCH-100): у watchdog СВОЙ Telegram-бот — независимый канал алертов. +# Переиспользовать токен орка (ORCH_TELEGRAM_BOT_TOKEN) ЗАПРЕЩЕНО: упавший +# орк не сможет сообщить о себе своим же ботом. +# * Когерентность порта: WATCHDOG_METRICS_URL следует за прод-портом +# (ORCH_DEPLOY_PROD_TARGET_PORT) — сменил порт орка → обнови URL здесь. +# * Key-set этого файла = блок WATCHDOG_* в .env.example (канон ключей); +# синхронность держит tests/test_lite_setup_doc.py (key-sync, TC-02b). +# Значения = дефолты watchdog/config.py. + +WATCHDOG_ENABLED=true +WATCHDOG_INTERVAL_S=30 +WATCHDOG_HTTP_TIMEOUT_S=5 +WATCHDOG_COOLDOWN_S=1800 +WATCHDOG_METRICS_URL=http://127.0.0.1:8500/metrics +WATCHDOG_ORCH_DOWN_TICKS=3 +WATCHDOG_MEM_PCT=90 +WATCHDOG_DISK_CRIT_ENABLED=false +WATCHDOG_DISK_CRIT_PCT=97 +WATCHDOG_DISK_PATHS=/repos,/app/data +WATCHDOG_AGENT_HUNG_MIN=20 +WATCHDOG_AGENT_CPU_FLOOR=0.01 +WATCHDOG_STAGE_STUCK_MIN=120 +WATCHDOG_QUEUE_DEPTH=20 +WATCHDOG_CONTAINERS=orchestrator +WATCHDOG_DOCKER_SOCK=/var/run/docker.sock +WATCHDOG_DEPS= +WATCHDOG_TG_BOT_TOKEN= +WATCHDOG_TG_CHAT_ID= diff --git a/.gitignore b/.gitignore index 90996a7..71efb16 100644 --- a/.gitignore +++ b/.gitignore @@ -7,5 +7,7 @@ data/ .pytest_cache/ # ORCH-31: staging env (secrets, not committed — see .env.staging.example) .env.staging +# ORCH-102: sidecar-watchdog env (secrets, not committed — see .env.watchdog.example) +.env.watchdog # ORCH-31: staging DB data directory data/staging/ diff --git a/CHANGELOG.md b/CHANGELOG.md index f0e1a57..fd9cbaf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,12 @@ Формат: [Keep a Changelog](https://keepachangelog.com/). Записи — на смысловой PR/задачу. ## [Unreleased] +- **ORCH-10a Lite-тираж: инструкция LITE_SETUP + канон watchdog-конфига + анти-дрейф контур** (ORCH-102, `docs`): закрыт Type A эпика ORCH-10 — заказчик разворачивает у себя **только орк+watchdog** и донастраивает окружение (Plane/Gitea/Telegram/LLM) по одной сквозной инструкции «голый хост → работающий конвейер». **Docs+tests** (паттерн ORCH-077/092): `src/**`/`docker-compose.yml`/`Dockerfile`/`scripts/**` — ноль изменений; конвейер (`STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict/схема БД) — байт-в-байт. ADR: `docs/work-items/ORCH-102/06-adr/ADR-001-lite-setup-doc-canon.md`, сквозной `adr-0037-lite-replication-canon.md`. + - **Главный продукт (D1/D2):** новый docs-раздел `docs/deployment/` (витрина тиража, читатель — внешний оператор) с golden source `docs/deployment/LITE_SETUP.md` — 13 нормативных разделов в порядке маршрута оператора (рамка → предусловия хоста → перенос кода → конфигурация → Plane → Gitea → LLM → Telegram → запуск → регистрация проекта → smoke → stateless-проверка → траблшутинг ×7); каждый шаг = fenced-команда + явная «Проверка:»/PASS/FAIL; хост-специфика — только плейсхолдеры `<...>`/`$ENV_VAR`; канон не форкается — статусы/env/вебхуки/smoke ссылками на ONBOARDING §1 / REPLICATION §2–§4 / SETUP_WEBHOOKS. + - **Канон watchdog-конфига (D5, исход А-4):** новый `.env.watchdog.example` (третий env-example; key-set = блок `WATCHDOG_*` `.env.example`, 19 ключей, токены — пустые плейсхолдеры) закрывает ловушку файла-носителя: sidecar читает ТОЛЬКО `.env.watchdog`, ключ `WATCHDOG_*` в `.env` для него инертен; шапка несёт C-1 (ORCH-100: свой бот, токен орка переиспользовать запрещено) и когерентность порта `WATCHDOG_METRICS_URL` ⇄ `ORCH_DEPLOY_PROD_TARGET_PORT`; `.env.watchdog` добавлен в `.gitignore` (секрет-гигиена, зеркало `.env.staging`). + - **Нормативы разделов:** Gitea (D3, исход А-1) — branch protection на `main` НЕ включать (ADR D10 ORCH-009: ломает PR-merge API merge-актора → ложные HOLD; INV-4), pre-receive хуки платформа не вводит, ОДИН глобальный webhook-секрет на все репо; staging-вилка (D6, исход А-5) — базовый Lite-контур БЕЗ staging (нужен только под self-hosting развитие платформы); источник кода (D7, исход А-6) — параметризованный `git clone `; stateless (AC-3) — пустая БД при первом старте, секреты только свежевыпущенные `gen_secrets.py`, явная проверка чистоты через `GET /queue`. + - **Анти-дрейф контур (D8):** новый `tests/test_lite_setup_doc.py` (25 структурных тестов, без сети/LLM/subprocess) — 13 разделов в порядке D2; обязательные кирпичи; key-sync `.env.watchdog.example` ⇄ `.env.example`; каждый упомянутый env-ключ существует в каноне; compose-подмножество (ровно 3 сервиса, staging строго за `profiles: [staging]`, дефолтный `up -d` = ровно орк+watchdog, анти-появление `plane*`/`gitea*`); fenced-скан боевых литералов (импорт `FORBIDDEN` из `test_no_host_hardcodes.py` — один источник истины) + эвристика секретоподобных значений с негативным самочеком; сверка «22 статуса» импортом `plane_sync._PLANE_NAME_TO_KEY`; перекрёстность REPLICATION→LITE_SETUP + CHANGELOG. + - **Перекрёстные доки (FR-7):** REPLICATION.md §1 — строка «Type A — Lite» → ✅ ORCH-102 + ссылка; README.md — способность Lite-тиража + `docs/deployment/` в структуре; INFRA.md — `.env.watchdog` в секрет-нормативе + ссылка на deployment-раздел; CLAUDE.md — блок ORCH-102. - **Фундамент тиража 10-common: расхардкод хоста + секреты нового хоста + smoke-процедура** (ORCH-101, `feat`): платформа разворачивается на новой инфре **без правки кода** — только env/конфиг (эпик ORCH-10, критический путь обоих типов A Lite / B Bundled; stateless по решению 10.06). Конвейер (`STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict/схема БД) — байт-в-байт не тронут; **каждый дефолт = боевому значению** → пустой/неизменённый `.env` ⇒ поведение 1:1 (kill-switch-природа, отдельный флаг не вводится — NFR-2; enduro не затронут). ADR: `docs/work-items/ORCH-101/06-adr/ADR-001-host-parametrization-secrets-smoke.md`, сквозной `adr-0036-replication-foundation-host-parametrization.md`. - **Расхардкод (D2, FR-1/FR-2):** четыре код-блокера закрыты тремя новыми `Settings`-ключами + реюзом существующих: `agent_home_dir` (`ORCH_AGENT_HOME_DIR`, HOME всех акторских env), `agent_git_name`/`git_email_domain` (`ORCH_AGENT_GIT_NAME`/`ORCH_GIT_EMAIL_DOMAIN`, git-идентичность: агенты — `claude-bot@<домен>` через единый `launcher.agent_git_env()` ×2 места; системные акторы держат платформенные имена `deploy-finalizer`/`post-deploy-monitor` под тем же доменом). `plane_sync.notify_stage_change` строит ссылки Branch/PR из `gitea_public_url`(fallback `gitea_url`)+`gitea_owner` вместо литералов `git.mva154.duckdns.org`/`admin`. `SELF_HOSTING_REPO` — **нормативная платформенная константа** тиража (D3: конфиг-ключ превращал бы опечатку в активацию деплой-машинерии на чужом репо или тихое выключение всех self-гейтов), пин-тест. - **Staging-порт + исполняемый инвариант ORCH-058 (D4):** `_STAGING_PORT` → ключ `staging_port` (`ORCH_STAGING_PORT`, дефолт 8501; то же имя интерполируется в compose `command:` staging — один факт, одно имя); в начале freshness-пути новый **fail-closed guard**: `staging_port == deploy_prod_target_port` → отказ «staging rebuild refused» + Telegram-алерт, **без тихого fallback** — анти-prod-гарантия из подразумеваемой константы стала исполняемой. Имена сервисов/профиля остаются константами. diff --git a/CLAUDE.md b/CLAUDE.md index 2772299..926fdd1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -321,6 +321,35 @@ API → `manual-step` (fail-safe); **runbook** `docs/operations/ONBOARDING.md` ( `docs/work-items/ORCH-101/06-adr/ADR-001-host-parametrization-secrets-smoke.md`, сквозной `docs/architecture/adr/adr-0036-replication-foundation-host-parametrization.md`. +## Lite-тираж: орк+watchdog на инфре заказчика (ORCH-102) +Закрыт **Type A** эпика ORCH-10 (поверх фундамента 10-common ORCH-101): заказчик разворачивает +у себя ТОЛЬКО `orchestrator`+`orchestrator-watchdog` и донастраивает окружение +(Plane/Gitea/Telegram/LLM — его инсталляции) по одной сквозной инструкции. **Docs+tests** +(паттерн ORCH-077/092): `src/**`/compose/Dockerfile/`scripts/**` не тронуты; конвейер байт-в-байт. +- **Golden source** — `docs/deployment/LITE_SETUP.md` (новый раздел `docs/deployment/` — витрина + тиража, читатель — внешний оператор; vs `docs/operations/` — эксплуатация НАШЕГО прода): 13 + нормативных разделов в порядке маршрута оператора, каждый шаг = fenced-команда + явная + «Проверка:»/PASS/FAIL, хост-специфика только плейсхолдерами; канон не форкается — статусы/env/ + вебхуки/smoke ссылками на ONBOARDING §1 / REPLICATION §2–§4 / SETUP_WEBHOOKS (явно в доке — + только fail-closed имена `Confirm Deploy`/`STOP` и обязательные ключи нового хоста). +- **Канон watchdog-конфига** — новый `.env.watchdog.example` (key-set = блок `WATCHDOG_*` + `.env.example`, держится key-sync тестом): sidecar читает ТОЛЬКО `.env.watchdog`, ключ + `WATCHDOG_*` в `.env` для него инертен (ловушка файла-носителя закрыта); C-1 ORCH-100 — свой + бот, токен орка не переиспользовать; `.env.watchdog` в `.gitignore`. +- **Нормативы:** Gitea — branch protection на `main` НЕ включать (ADR D10 ORCH-009 / INV-4), + pre-receive не вводится, ОДИН глобальный webhook-секрет; compose НЕ форкается (дефолтный + `up -d` = ровно орк+watchdog, staging строго за `profiles: [staging]` — вилка только под + self-hosting развитие платформы); stateless — данные/задачи/секреты боевого хоста НЕ + переносятся, проверка чистоты через `GET /queue`. +- **Анти-дрейф** — `tests/test_lite_setup_doc.py` (структурный, без сети/LLM/subprocess): + 13 разделов в порядке, кирпичи, env-ключи ⊂ `.env.example`, compose-подмножество + (анти-появление `plane*`/`gitea*`), fenced-скан `FORBIDDEN` (импорт из + `test_no_host_hardcodes.py`) + секрет-эвристика, «22 статуса» сверкой импорта + `plane_sync._PLANE_NAME_TO_KEY`, перекрёстность REPLICATION→LITE_SETUP. **Норматив + сопровождения (NFR-5):** меняешь шаги тиража → обнови LITE_SETUP.md в том же PR. Детали — + `docs/work-items/ORCH-102/06-adr/ADR-001-lite-setup-doc-canon.md`, сквозной + `docs/architecture/adr/adr-0037-lite-replication-canon.md`. + ## Конвенции - Conventional Commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`) - Ветки: `feature/ORCH-NNN-slug`, `fix/ORCH-NNN-slug` diff --git a/README.md b/README.md index ea13001..5f7bb1f 100644 --- a/README.md +++ b/README.md @@ -70,6 +70,8 @@ data/ └── runs/ # Agent output logs ({run_id}.log) docs/ ├── PRODUCT_VISION.md # Видение продукта +├── deployment/ +│ └── LITE_SETUP.md # Lite-тираж: орк+watchdog на инфре заказчика (ORCH-102) ├── architecture/ │ ├── README.md # Обзор архитектуры, компоненты, API │ ├── internals.md # Схема БД, потоки, resilience-слой @@ -151,6 +153,10 @@ uvicorn src.main:app --reload --port 8500 | `ORCH_RUN_UID` / `ORCH_RUN_GID` / `ORCH_DOCKER_GID` | ORCH-101: uid:gid контейнера и gid docker-группы (`group_add`, ORCH-040) | `1000`/`1000`/`999` | Тираж платформы на новый хост (полная карта, секреты, smoke) — `docs/operations/REPLICATION.md` (ORCH-101). +**Lite-тираж под ключ (ORCH-102):** разворачивание орк+watchdog на инфраструктуре заказчика +по одной сквозной инструкции «голый хост → работающий конвейер» (Plane/Gitea/Telegram/LLM +заказчик ставит сам и подключает по шагам) — `docs/deployment/LITE_SETUP.md`; канон конфига +sidecar-watchdog — `.env.watchdog.example`; анти-дрейф — `tests/test_lite_setup_doc.py`. ## Очередь задач (ORCH-1 / F-2b) diff --git a/docs/deployment/LITE_SETUP.md b/docs/deployment/LITE_SETUP.md new file mode 100644 index 0000000..50bc5b0 --- /dev/null +++ b/docs/deployment/LITE_SETUP.md @@ -0,0 +1,596 @@ +# LITE_SETUP — Lite-тираж: оркестратор + watchdog на вашей инфраструктуре (ORCH-102) + +> **Golden source Lite-тиража (Type A эпика ORCH-10).** Сквозной маршрут +> «голый хост → работающий конвейер» для внешнего оператора/заказчика. Каждый шаг — +> исполняемая команда + явная проверка результата (**Проверка:** / PASS / FAIL). +> Хост-специфика в командах — только плейсхолдеры `<...>` и `$ENV_VAR`. +> Тираж **stateless**: данные/задачи/секреты исходного (боевого) хоста **НЕ переносятся** +> ни на одном шаге — всё создаётся заново (§12). + +--- + +## 1. Рамка Lite + +**Что разворачиваем:** два контейнера платформы — `orchestrator` (конвейер, порт +`ORCH_DEPLOY_PROD_TARGET_PORT`, дефолт 8500) и `orchestrator-watchdog` +(независимый sidecar-мониторинг). Третий сервис `orchestrator-staging` существует в том же +compose-файле, но строго за профилем `staging` и в базовом Lite-контуре не поднимается (§9). + +**Что заказчик ставит и администрирует сам** (вне этой инструкции — как продукты): +- **Plane** (task-management) — своя инсталляция; здесь только её *подключение* (§5); +- **Gitea** (git-хостинг) — своя инсталляция; здесь только её *подключение* (§6); +- **Telegram-боты** (нотификации) — свои боты (§8); +- **LLM-доступ** (claude CLI + node) — свой дистрибутив и аутентификация (§7). + +**Границы слоёв тиража** (10-common vs Lite vs Bundled) — `docs/operations/REPLICATION.md` §1. +Этот док собирает кирпичи 10-common (карта env, секреты, smoke) в один маршрут и не форкает их. + +**Платформенные конвенции (не менять):** +- репо платформы обязан называться **`orchestrator`** (узел безопасности `SELF_HOSTING_REPO`); +- имена compose-сервисов/профиля (`orchestrator`, `orchestrator-watchdog`, + `orchestrator-staging`, профиль `staging`) — константы платформы; +- контейнерные пути (`/app/data`, `/repos`, `/opt/claude-code`) — layout контейнера, + не хост-значения; не параметризуются. + +--- + +## 2. Предусловия хоста + +Поддерживаемый контур: **Linux x86_64, Docker Engine + Compose v2, git, python3, node** + +дистрибутив claude-code на хосте. Вне контура — вне гарантии Lite. Каждое предусловие — +команда проверки; все проверки PASS → можно переходить к §3. + +**2.1. ОС и базовые зависимости.** + +```bash +uname -sm # Linux x86_64 +docker --version # Docker Engine +docker compose version # Compose v2 +git --version +python3 --version # 3.x (для scripts/*.py) +node --version # путь к бинарю станет ORCH_HOST_NODE_BIN +``` + +**Проверка:** все команды отвечают версиями без ошибок — PASS; любая отсутствует — FAIL +(доставить пакет средствами вашего дистрибутива). + +**2.2. Пользователь-владелец и uid/gid (инвариант ORCH-040).** Контейнеры бегут под +`ORCH_RUN_UID:ORCH_RUN_GID` — это обязан быть uid:gid владельца каталога репозиториев +`ORCH_HOST_REPOS_DIR`, иначе git-артефакты конвейера не запишутся. + +```bash +id -u ; id -g # значения для ORCH_RUN_UID / ORCH_RUN_GID +mkdir -p <путь-каталога-репозиториев> # станет ORCH_HOST_REPOS_DIR +stat -c '%u:%g' <путь-каталога-репозиториев> # обязан совпасть с ORCH_RUN_UID:ORCH_RUN_GID +``` + +**Проверка:** uid:gid владельца каталога = будущие `ORCH_RUN_UID`/`ORCH_RUN_GID` — PASS. + +**2.3. Группа docker (доступ к docker.sock).** + +```bash +getent group docker # третье поле — gid, станет ORCH_DOCKER_GID +``` + +**Проверка:** строка вида `docker:x::...` есть — PASS; группы нет — FAIL +(установите Docker корректно / создайте группу). + +**2.4. Каталог ssh-ключей деплой-хука** (понадобится для git-push артефактов агентов и +деплой-хуков; монтируется в `$HOME/.ssh` акторов). + +```bash +mkdir -p <путь-ssh-каталога> # станет ORCH_HOST_SSH_DIR +ssh-keygen -t ed25519 -f <путь-ssh-каталога>/id_ed25519 -N "" -C "orchestrator@" +ls -l <путь-ssh-каталога> # ключи читаемы пользователем из 2.2 +``` + +**Проверка:** каталог существует, ключи на месте, владелец — пользователь из 2.2 — PASS. +Публичный ключ добавьте в Gitea (Settings → SSH Keys) на шаге §6. + +**2.5. Свободные порты** (дефолты платформы: 8500 — прод, 8501 — staging). + +```bash +ss -ltn | grep -E ':(8500|8501)\b' || echo "ports free" +``` + +**Проверка:** вывод `ports free` — PASS. Порты заняты → выберите другие и на шаге §4 +синхронно задайте `ORCH_DEPLOY_PROD_TARGET_PORT` ⇄ `WATCHDOG_METRICS_URL` ⇄ +`ORCH_POST_DEPLOY_BASE_URL` (и `ORCH_STAGING_PORT` ≠ прод-порт — guard ORCH-058 fail-closed). + +--- + +## 3. Перенос кода + +Переносится **только код** — чекаут репо `orchestrator`. **НИКАКИХ** данных, БД или `.env` +с исходного хоста (норматив §12). Watchdog отдельно не переносится: его код — каталог +`watchdog/` того же репо, образ собирается локально compose'ом. + +```bash +git clone <путь-чекаута> # путь станет ORCH_DEPLOY_HOST_REPO_PATH +cd <путь-чекаута> +``` + +Конкретный канал дистрибуции (`` — зеркало/архив/доступ к +Gitea поставщика) согласуйте с поставщиком платформы; опционально — `--branch <тег-среза>`. + +**Проверка:** + +```bash +git -C <путь-чекаута> log --oneline -1 # коммит виден +ls <путь-чекаута>/docker-compose.yml <путь-чекаута>/watchdog/Dockerfile \ + <путь-чекаута>/.env.example <путь-чекаута>/.env.watchdog.example +``` + +Все файлы на месте — PASS. + +--- + +## 4. Конфигурация + +`.env` собирается **с нуля от канона `.env.example`** (100% ключей старта; полная карта +переменных и их семантика — `docs/operations/REPLICATION.md` §2). Дефолт каждого ключа = +значению исходного хоста, поэтому задаёте только то, что отличается у вас. + +**4.1. Создать `.env` и выпустить webhook-секреты.** + +```bash +cd <путь-чекаута> +cp .env.example .env +python3 scripts/gen_secrets.py # печатает свежие ORCH_PLANE_WEBHOOK_SECRET / ORCH_GITEA_WEBHOOK_SECRET +``` + +Вставьте оба напечатанных значения в `.env`. Секреты выпускаются **только заново** — +боевые не копируются (§12). + +**4.2. Обязательные ключи нового хоста** (заполняются в `.env` по ходу §5–§8): + +| Группа | Ключи | Откуда | +|--------|-------|--------| +| Plane | `ORCH_PLANE_API_URL`, `ORCH_PLANE_WEB_URL`, `ORCH_PLANE_WORKSPACE_SLUG`, `ORCH_PLANE_API_TOKEN` | §5 | +| Gitea | `ORCH_GITEA_URL`, `ORCH_GITEA_PUBLIC_URL`, `ORCH_GITEA_OWNER`, `ORCH_GITEA_TOKEN` | §6 | +| Webhook-секреты | `ORCH_PLANE_WEBHOOK_SECRET`, `ORCH_GITEA_WEBHOOK_SECRET` | 4.1 (`gen_secrets.py`) | +| Telegram | `ORCH_TELEGRAM_BOT_TOKEN`, `ORCH_TELEGRAM_CHAT_ID` | §8 | +| Реестр проектов | `ORCH_PROJECTS_JSON` — **обязателен**: встроенный fallback несёт Plane-UUID исходного хоста | §10 | +| Хост-параметры | `ORCH_AGENT_HOME_DIR`, `ORCH_HOST_REPOS_DIR`, `ORCH_HOST_CLAUDE_DIR`, `ORCH_HOST_CLAUDE_JSON`, `ORCH_HOST_SSH_DIR`, `ORCH_HOST_CLAUDE_CODE_DIR`, `ORCH_HOST_NODE_BIN`, `ORCH_RUN_UID`, `ORCH_RUN_GID`, `ORCH_DOCKER_GID`, `ORCH_DEPLOY_HOST_REPO_PATH`, `ORCH_AGENT_GIT_NAME`, `ORCH_GIT_EMAIL_DOMAIN` | значения из §2–§3 | +| Порты | `ORCH_DEPLOY_PROD_TARGET_PORT` ⇄ `WATCHDOG_METRICS_URL` ⇄ `ORCH_POST_DEPLOY_BASE_URL`; `ORCH_STAGING_PORT` ≠ прод-порт | §2.5 | + +**4.3. Конфиг sidecar-watchdog — отдельный файл-носитель.** Sidecar-контейнер читает +**ТОЛЬКО `.env.watchdog`**; ключ `WATCHDOG_ENABLED` (и любой другой `WATCHDOG_*`), +положенный в `.env`, для sidecar **инертен**. + +```bash +cp .env.watchdog.example .env.watchdog +# заполнить два ключа: WATCHDOG_TG_BOT_TOKEN / WATCHDOG_TG_CHAT_ID (бота создадим в §8) +``` + +**Проверка (резолв всей конфигурации):** + +```bash +docker compose config >/dev/null && echo "compose config: PASS" +``` + +`PASS` без ошибок интерполяции — конфигурация согласована; ошибка — FAIL (ищите +незакрытую кавычку/невалидный JSON в `ORCH_PROJECTS_JSON`). + +--- + +## 5. Подключение Plane + +Инсталляция Plane — ваша; платформа подключается к ней API-токеном и webhook'ом. + +**5.1. Workspace и проект.** Создайте workspace (его slug → `ORCH_PLANE_WEB_URL` / +`ORCH_PLANE_WORKSPACE_SLUG`) и проект под вашу разработку — через UI Plane. + +```bash +# базовая доступность API из хоста оркестратора: +curl -fsS "$ORCH_PLANE_API_URL/api/v1/workspaces//projects/" \ + -H "X-API-Key: " | head -c 200 +``` + +**Проверка:** HTTP 200 и JSON со списком проектов — PASS; 401/403 — токен (5.2) ещё не +выпущен или не имеет прав. + +**5.2. API-токен.** Plane UI → Workspace Settings → API tokens → выпустить токен → +`ORCH_PLANE_API_TOKEN` в `.env`. Токен должен иметь право создавать проекты/статусы +(нужно для `onboard_project.py apply`, §10). + +**5.3. Модель статусов — НЕ вручную.** Конвейеру нужны **22 канонических статуса** с +точными именами и группами; их создаёт `python3 scripts/onboard_project.py apply` (§10), +полная таблица — `docs/operations/ONBOARDING.md` §1 (golden source; здесь не дублируется). +Два имени фиксируем явно, потому что они **fail-closed** (без них ветка просто не +активируется, без ошибки): **`Confirm Deploy`** (человеческий гейт прод-деплоя) и +**`STOP`** (отмена задачи; обязан быть в группе `cancelled`). + +```bash +# после §10 — проверить, что статусы созданы: +curl -fsS "$ORCH_PLANE_API_URL/api/v1/workspaces//projects//states/" \ + -H "X-API-Key: $ORCH_PLANE_API_TOKEN" | python3 -m json.tool | grep -c '"name"' +``` + +**Проверка:** счётчик имён = 22 (или больше, если в проекте остались дефолтные статусы +Plane) и среди них `Confirm Deploy` и `STOP` — PASS. + +**5.4. Webhook + HMAC.** Приёмник — `POST https:///webhook/plane`; +подпись — заголовок `X-Plane-Signature` (HMAC-SHA256, hex digest); секрет — значение +`ORCH_PLANE_WEBHOOK_SECRET` из 4.1. События: Issue, Issue Comment. + +**Каверза Plane CE:** webhook **не экспонирован во внешнем `/api/v1`** — настраивается +одним из двух путей. + +*Путь А — UI (если ваша сборка Plane его показывает):* Workspace Settings → Webhooks → +Add Webhook → URL + Secret (значение `ORCH_PLANE_WEBHOOK_SECRET`) → события Issue, +Issue Comment → Save. + +*Путь Б — прямой SQL в Postgres инсталляции Plane:* + +```bash +WORKSPACE_ID=$(docker exec -e PGPASSWORD= \ + psql -U plane -d plane -t -A -c "SELECT id FROM workspaces WHERE slug=''") +WEBHOOK_ID=$(cat /proc/sys/kernel/random/uuid) +docker exec -e PGPASSWORD= psql -U plane -d plane -c " +INSERT INTO webhooks (id, created_at, updated_at, deleted_at, workspace_id, url, is_active, + secret_key, project, issue, module, cycle, issue_comment, is_internal, version) +VALUES ('${WEBHOOK_ID}', NOW(), NOW(), NULL, '${WORKSPACE_ID}', + 'https:///webhook/plane', + true, '<значение ORCH_PLANE_WEBHOOK_SECRET>', true, true, false, false, true, false, 'v1'); +" +``` + +**Проверка:** + +```bash +docker exec -e PGPASSWORD= psql -U plane -d plane -c \ + "SELECT url, is_active FROM webhooks;" +``` + +Строка с вашим URL и `is_active = t` — PASS. Сквозная проверка доставки — §11 (smoke); +generic-образец команд и формат подписи — `docs/operations/SETUP_WEBHOOKS.md`. + +--- + +## 6. Подключение Gitea + +**6.1. Токен.** Gitea UI → Settings → Applications → Generate Token, scope: `repo`, +`admin:repo_hook` → `ORCH_GITEA_TOKEN` в `.env`. + +```bash +curl -fsS -H "Authorization: token $ORCH_GITEA_TOKEN" "$ORCH_GITEA_URL/api/v1/user" | head -c 200 +``` + +**Проверка:** HTTP 200 с JSON вашего пользователя — PASS; владелец репозиториев +(организация/пользователь) → `ORCH_GITEA_OWNER`, браузерный URL → `ORCH_GITEA_PUBLIC_URL`. + +**6.2. Репо проекта.** Создаёт `onboard_project.py apply` (§10) — или вручную (пустой +репо + initial push). Чекаут обязан появиться в `$ORCH_HOST_REPOS_DIR/` (общий +каталог репозиториев из §2.2). Публичный ключ из §2.4 добавьте в Gitea +(Settings → SSH Keys), чтобы акторы могли пушить. + +```bash +git -C "$ORCH_HOST_REPOS_DIR" clone +stat -c '%u:%g' "$ORCH_HOST_REPOS_DIR/" # владелец = ORCH_RUN_UID:ORCH_RUN_GID +``` + +**Проверка:** чекаут на месте, владелец совпадает — PASS. + +**6.3. Per-repo webhook.** Создаёт `onboard_project.py apply` (§10). Параметры (если +вручную): URL `https:///webhook/gitea`, content type `json`, +события **`push` / `pull_request` / `status`**, branch filter `*`, подпись — +`X-Gitea-Signature` (HMAC-SHA256). Секрет — **ОДИН глобальный `ORCH_GITEA_WEBHOOK_SECRET` +на ВСЕ репо** (приёмник валидирует только его; «свой секрет на репо» сломал бы HMAC +остальных). + +```bash +curl -fsS -H "Authorization: token $ORCH_GITEA_TOKEN" \ + "$ORCH_GITEA_URL/api/v1/repos///hooks" | python3 -m json.tool +``` + +**Проверка:** hook с вашим URL и тремя событиями существует, `active: true` — PASS. + +**6.4. Норматив защиты `main` (ВАЖНО).** **Branch protection на `main` НЕ включать** +(никаких required-approvals / required-status-checks): merge-актор конвейера мержит PR +строго через Gitea PR-merge API (INV-4), и protection-правила дают 405/409-класс отказов → +ложные HOLD задач (ADR D10 ORCH-009). **pre-receive хуки платформа не вводит** и не +проверяет — защита `main` держится конвенцией (агенты не пушат `main`) + скоупом токенов. + +```bash +curl -fsS -H "Authorization: token $ORCH_GITEA_TOKEN" \ + "$ORCH_GITEA_URL/api/v1/repos///branch_protections" | python3 -m json.tool +``` + +**Проверка:** пустой список `[]` — PASS; есть правила на `main` — FAIL (удалите их, +симптом «PR не мержится / HOLD» — §13.7). + +--- + +## 7. LLM (claude CLI) + +Агенты конвейера — процессы claude CLI **внутри контейнера**, но дистрибутив, node и +аутентификация живут **на хосте** и пробрасываются маунтами (источники маунтов = +ключи `.env`). + +**7.1. Дистрибутив claude-code и node.** Установите claude-code (npm-дистрибутив +Anthropic) и node на хост. Пути → `.env`: + +```bash +which node # → ORCH_HOST_NODE_BIN +npm root -g # каталог глобальных модулей +ls "/@anthropic-ai/claude-code" # → ORCH_HOST_CLAUDE_CODE_DIR +``` + +**Проверка:** каталог дистрибутива существует и непуст — PASS. Внутри контейнера бинарь +доступен как `ORCH_CLAUDE_BIN` (дефолт менять не нужно). + +**7.2. Аутентификация CLI.** Выполните первичный интерактивный логин claude CLI **на +хосте** под пользователем из §2.2 (по инструкции Anthropic к claude-code). Логин создаёт +каталог `~/.claude` и файл `~/.claude.json` — их пути задайте в `ORCH_HOST_CLAUDE_DIR` / +`ORCH_HOST_CLAUDE_JSON`. + +```bash +claude --version # CLI работает +sudo -u "#" test -r <путь-~/.claude>/.credentials.json && echo "creds: PASS" +``` + +**Проверка:** версия печатается; `creds: PASS` — креды читаемы uid'ом контейнера +(иначе — `chown -R :` каталога, симптом §13.3). + +**7.3. Модели агентов.** Резолв модели/эффорта — только из конфига (ORCH-41/74): +дефолты канона уже в `.env.example` (`ORCH_AGENT_MODEL_DEFAULT`, +`ORCH_AGENT_EFFORT_DEFAULT` и per-агент ключи рядом) — менять не обязательно. + +```bash +grep -E '^ORCH_AGENT_(MODEL|EFFORT)_DEFAULT=' .env +``` + +**Проверка:** оба ключа присутствуют и непусты — PASS. + +--- + +## 8. Telegram + +Каналов **два и они независимы** (C-1 ORCH-100): бот live-трекера оркестратора и +**отдельный** бот sidecar-watchdog. Токен орка для watchdog переиспользовать +**ЗАПРЕЩЕНО** — упавший орк не сможет сообщить о себе своим же ботом. + +**8.1. Бот трекера.** BotFather → `/newbot` → токен → `ORCH_TELEGRAM_BOT_TOKEN` в `.env`. + +```bash +curl -fsS "https://api.telegram.org/bot<токен-трекера>/getMe" +# напишите боту любое сообщение (или добавьте его в чат), затем: +curl -fsS "https://api.telegram.org/bot<токен-трекера>/getUpdates" | python3 -m json.tool | grep -m1 '"id"' +``` + +**Проверка:** `getMe` → `"ok":true`; `id` чата из `getUpdates` → `ORCH_TELEGRAM_CHAT_ID` — +PASS. + +**8.2. Watchdog-бот (отдельный).** BotFather → `/newbot` ещё раз → токен и chat-id → +**`.env.watchdog`** (`WATCHDOG_TG_BOT_TOKEN` / `WATCHDOG_TG_CHAT_ID`). Помните о +файле-носителе: эти ключи работают только в `.env.watchdog` (§4.3). + +```bash +curl -fsS "https://api.telegram.org/bot<токен-watchdog>/getMe" +grep -E '^WATCHDOG_TG_(BOT_TOKEN|CHAT_ID)=.+' .env.watchdog +``` + +**Проверка:** `getMe` → `"ok":true`; оба ключа в `.env.watchdog` непусты — PASS. + +--- + +## 9. Запуск + +**9.1. Базовый Lite-контур (дефолт): орк + watchdog.** + +```bash +cd <путь-чекаута> +docker compose config --services # ровно: orchestrator, orchestrator-watchdog, orchestrator-staging +docker compose up -d --build +docker compose ps +``` + +**Проверка:** запущены **ровно два** контейнера — `orchestrator` и +`orchestrator-watchdog`; `orchestrator-staging` НЕ поднялся (он строго за +`profiles: [staging]`) — PASS. Поднялось что-то ещё/меньше — FAIL. + +**9.2. Health-чек контрактов.** + +```bash +curl -fsS http://127.0.0.1:8500/health +curl -fsS http://127.0.0.1:8500/queue | python3 -m json.tool | head -20 +curl -fsS http://127.0.0.1:8500/metrics | python3 -m json.tool | head -10 +``` + +**Проверка:** `/health` → HTTP 200, `"status":"ok"`; `/queue` → штатный JSON +(счётчики очереди); `/metrics` → JSON со `"schema_version": 1` — PASS. (Порт замените, +если меняли `ORCH_DEPLOY_PROD_TARGET_PORT`.) + +**9.3. Вилка staging (опционально).** Базовому контуру «гонять СВОИ проекты» staging +**не нужен**. Он нужен ТОЛЬКО если вы регистрируете проект `orchestrator` (self-hosting +развитие самой платформы у себя): стадия `deploy-staging` требует песочницу на +`ORCH_STAGING_PORT` (изолированная БД `./data/staging`; guard ORCH-058: staging-порт ≠ +прод-порт, fail-closed). + +```bash +cp .env.staging.example .env.staging # заполнить по аналогии с .env +docker compose --profile staging up -d orchestrator-staging +curl -fsS http://127.0.0.1:8501/health +``` + +**Проверка (только для этой вилки):** `/health` staging → 200 — PASS. + +--- + +## 10. Регистрация проекта заказчика + +Onboarding-CLI создаёт Plane-проект с 22 статусами и лейблами (`autoApprove` / +`autoDeploy` / `Bug`), Gitea-репо с webhook'ом, скелет репо (kit) и печатает merged-реестр. +Полный runbook — `docs/operations/ONBOARDING.md`; Lite-последовательность: + +```bash +cd <путь-чекаута> +python3 scripts/onboard_project.py plan \ + --name "<имя проекта>" --description "<зачем проект>" \ + --repo --prefix \ + --stack "<стек>" --test-cmd "<команда тестов>" \ + --prod-port <порт-прода-проекта> --staging-port <порт-staging-проекта> \ + --webhook-url https:///webhook/gitea +# план устроил → тот же вызов с apply; затем read-only контроль: +python3 scripts/onboard_project.py verify <те же аргументы> +``` + +**Проверка:** `apply` завершился без ошибок (exit 0; `2` = остались 🖐 ручные шаги — выполните +их по отчёту), `verify` зелёный — PASS. + +Дальше реестр и рестарт: + +```bash +# 1) строку ORCH_PROJECTS_JSON=[...] из отчёта apply вставить в .env (заменить целиком); +# 2) дождаться тихого окна и управляемо перезапустить орк: +curl -fsS http://127.0.0.1:8500/queue | python3 -m json.tool | head -20 # нет running-job +docker compose up -d --force-recreate orchestrator +# 3) убедиться, что инстанс жив и реестр подхвачен: +curl -fsS http://127.0.0.1:8500/health +curl -fsS http://127.0.0.1:8500/queue | python3 -m json.tool | head -20 +``` + +**Проверка:** `/health` → 200 после рестарта; в Plane создан проект со статусами +(см. §5.3), в Gitea — репо с webhook (§6.3) — PASS. + +--- + +## 11. Smoke: «конвейер доехал» + +Процедура — чек-лист `docs/operations/REPLICATION.md` §4 (шаги 0–5; шаг 6 «до `done`» — +опционально), без форка; каждый шаг несёт явный PASS/FAIL. Lite-предусловия: §2–§10 этого +дока выполнены, проект заказчика зарегистрирован (§10). + +Минимальный сигнал «конвейер доехал» (шаги 4–5 чек-листа): создайте issue в Plane-проекте +и переведите в статус **To Analyse**, затем: + +```bash +# задача появилась и analyst-job в очереди: +curl -fsS http://127.0.0.1:8500/queue | python3 -m json.tool | head -40 +# по завершении стадии analysis — артефакты 01–04 в ветке задачи: +git -C "$ORCH_HOST_REPOS_DIR/" fetch origin +git -C "$ORCH_HOST_REPOS_DIR/" ls-tree --name-only origin/<ветка-задачи> "docs/work-items//" +``` + +**Проверка:** в `/queue` виден job задачи; `ls-tree` показывает `01-brd.md` … +`04-test-plan.yaml` — PASS. + +**Итоговый вердикт:** все шаги чек-листа PASS ⇒ **тираж PASS**; любой шаг FAIL ⇒ тираж +FAIL — соберите `docker logs orchestrator --tail 100` и снапшот `GET /queue`, разбор — +§13. + +--- + +## 12. Stateless-проверка + +**Нормативно: данные/задачи/секреты боевого (исходного) хоста НЕ переносятся** (зеркало +`docs/operations/REPLICATION.md` §5). БД создаётся **пустой** при первом старте; `.env` / +`.env.staging` / `.env.watchdog` собраны с нуля (§4); секреты — только свежевыпущенные +(`gen_secrets.py` + чек-лист внешних токенов `docs/operations/REPLICATION.md` §3). + +Проверка чистоты развёрнутого инстанса (выполнить ДО первой своей задачи): + +```bash +ls -la <путь-чекаута>/data/ # БД появилась только после первого старта +curl -fsS http://127.0.0.1:8500/queue | python3 -m json.tool # счётчики jobs нулевые +``` + +**Проверка:** в `/queue` нулевые счётчики и НИ ОДНОЙ задачи чужих проектов (никаких +`ORCH-*`/`ET-*` исходного хоста) — PASS. Любая чужая задача/перенесённый файл БД — FAIL: +инстанс собран не stateless, пересоберите `data/` с нуля. + +--- + +## 13. Траблшутинг первичной настройки + +Формат: симптом → команда диагностики → лечение. + +**13.1. Webhook отвечает 401 / HMAC mismatch.** + +```bash +docker logs orchestrator --tail 50 2>&1 | grep -i "webhook\|signature\|401" +``` + +Лечение: секрет в `.env` (`ORCH_PLANE_WEBHOOK_SECRET` / `ORCH_GITEA_WEBHOOK_SECRET`) +обязан **байт-в-байт** совпадать с секретом в настройке webhook'а (Plane §5.4 / Gitea +§6.3); после правки `.env` — управляемый рестарт (§10). Формат подписи — +`docs/operations/SETUP_WEBHOOKS.md`. + +**13.2. Задача в Plane создана, но в оркестраторе не появилась.** + +```bash +curl -fsS http://127.0.0.1:8500/queue | python3 -m json.tool | head -30 # есть ли job +docker logs orchestrator --tail 50 2>&1 | grep -i "ignored\|unknown project" +grep ORCH_PROJECTS_JSON .env # uuid вашего проекта в реестре? +``` + +Лечение: (а) проект отсутствует/с чужим UUID в `ORCH_PROJECTS_JSON` → поправить реестр +(§10) + рестарт; (б) webhook не доставлен → Plane: `SELECT url, is_active FROM webhooks;` +(§5.4), Gitea: Recent Deliveries в настройках hook'а; (в) подпись → §13.1. + +**13.3. claude CLI не найден / не аутентифицирован (агент падает на старте).** + +```bash +docker exec orchestrator /usr/bin/claude --version +sudo -u "#" test -r <путь-~/.claude>/.credentials.json && echo "creds: PASS" +``` + +Лечение: маунты указывают на фактические пути хоста (`ORCH_HOST_CLAUDE_CODE_DIR`, +`ORCH_HOST_NODE_BIN`, `ORCH_HOST_CLAUDE_DIR`, `ORCH_HOST_CLAUDE_JSON` в `.env`); креды +читаемы uid'ом из §2.2 (`chown -R :`); при невалидной сессии — повторный логин +на хосте (§7.2) + `docker compose up -d --force-recreate orchestrator`. + +**13.4. `docker.sock: permission denied` в логах орка/watchdog.** + +```bash +getent group docker # фактический gid +grep ORCH_DOCKER_GID .env # gid в конфиге +``` + +Лечение: значения обязаны совпадать → выставить `ORCH_DOCKER_GID` = фактическому gid и +`docker compose up -d --force-recreate`. + +**13.5. `Permission denied` при создании worktree (права `/repos`, ORCH-040/057).** + +```bash +stat -c '%u:%g' "$ORCH_HOST_REPOS_DIR" "$ORCH_HOST_REPOS_DIR/" +grep -E '^ORCH_RUN_(UID|GID)=' .env +``` + +Лечение: владелец каталога репо обязан совпадать с `ORCH_RUN_UID:ORCH_RUN_GID` +(§2.2) → `chown -R : "$ORCH_HOST_REPOS_DIR"` (включая legacy root-owned файлы) +и пересоздать контейнер. + +**13.6. Telegram молчит (нет карточек/алертов).** + +```bash +curl -fsS "https://api.telegram.org/bot<токен-трекера>/getMe" +curl -fsS "https://api.telegram.org/bot<токен-watchdog>/getMe" +grep -E '^ORCH_TELEGRAM_(BOT_TOKEN|CHAT_ID)=.+' .env +grep -E '^WATCHDOG_TG_(BOT_TOKEN|CHAT_ID)=.+' .env.watchdog +``` + +Лечение: оба бота отвечают `"ok":true`; chat-id корректен (бот добавлен в чат / получил +сообщение); ключи watchdog-бота лежат именно в `.env.watchdog` (в `.env` они инертны, +§4.3); пустой токен = режим «логи без отправки» (fail-safe, не ошибка). + +**13.7. PR задачи не мержится / задача в HOLD.** Первая проверка — **не включена ли +branch protection на `main`** (§6.4): + +```bash +curl -fsS -H "Authorization: token $ORCH_GITEA_TOKEN" \ + "$ORCH_GITEA_URL/api/v1/repos///branch_protections" | python3 -m json.tool +``` + +Лечение: непустой список правил на `main` → удалить (норматив §6.4); merge выполняет +PR-merge API оркестратора, ручной merge не требуется. + +--- + +*Golden source Lite-тиража (ORCH-102, ADR-001). **Норматив сопровождения (NFR-5):** +меняешь шаги тиража (env-ключи, compose-сервисы, маршрут онбординга, smoke) → обнови +этот док В ТОМ ЖЕ PR (правило агентов №2). Полноту и гигиену дока держит структурный +анти-дрейф тест `tests/test_lite_setup_doc.py`; кирпичи-каноны: REPLICATION.md (карта +env §2, секреты §3, smoke §4), ONBOARDING.md (статусы §1, онбординг), SETUP_WEBHOOKS.md +(формат вебхуков), `.env.example` / `.env.watchdog.example` (канон ключей).* diff --git a/docs/operations/INFRA.md b/docs/operations/INFRA.md index 1249c07..e52e67d 100644 --- a/docs/operations/INFRA.md +++ b/docs/operations/INFRA.md @@ -179,7 +179,7 @@ watchdog'а: **watchdog сигналит, pruner убирает**. | `ORCH_RUN_UID` / `ORCH_RUN_GID` | ORCH-101: uid:gid контейнера (`user:`) + `ARG APP_UID/APP_GID` (дефолт `1000:1000`, ORCH-040) | | `ORCH_DOCKER_GID` | ORCH-101: gid docker-группы хоста для `group_add` (дефолт `999`; «МИНА 1» ORCH-040 — не удалять) | -**Секреты — только в `.env` / `.env.staging` на хосте, в гит НЕ коммитятся.** Канон — `.env.example`, `.env.staging.example`. Выпуск нового комплекта секретов для нового хоста — `scripts/gen_secrets.py` (боевые секреты не копируются). **Тираж платформы на новую инфру** (карта переменных, секреты, smoke-процедура, границы Lite/Bundled) — `docs/operations/REPLICATION.md` (ORCH-101). Когерентность портов при смене прод-порта: `ORCH_DEPLOY_PROD_TARGET_PORT` ⇄ `WATCHDOG_METRICS_URL` ⇄ `ORCH_POST_DEPLOY_BASE_URL`. +**Секреты — только в `.env` / `.env.staging` / `.env.watchdog` на хосте, в гит НЕ коммитятся.** Канон — `.env.example`, `.env.staging.example`, `.env.watchdog.example` (ORCH-102: sidecar-watchdog читает ТОЛЬКО `.env.watchdog`; `WATCHDOG_*` в `.env` для него инертен). Выпуск нового комплекта секретов для нового хоста — `scripts/gen_secrets.py` (боевые секреты не копируются). **Тираж платформы на новую инфру** (карта переменных, секреты, smoke-процедура, границы Lite/Bundled) — `docs/operations/REPLICATION.md` (ORCH-101); сквозная инструкция Lite-тиража для внешнего оператора («голый хост → конвейер», орк+watchdog) — `docs/deployment/LITE_SETUP.md` (ORCH-102). Когерентность портов при смене прод-порта: `ORCH_DEPLOY_PROD_TARGET_PORT` ⇄ `WATCHDOG_METRICS_URL` ⇄ `ORCH_POST_DEPLOY_BASE_URL`. ## Реестр проектов (`src/projects.py`, ORCH-6) Связывает Plane project id → gitea repo + work-item prefix. Источник: `ORCH_PROJECTS_JSON`, fallback — встроенный дефолт. Прод видит: `enduro-trails` (ET), `orchestrator` (ORCH). Staging видит ТОЛЬКО `orchestrator-sandbox` (SANDBOX) — изоляция. diff --git a/docs/operations/REPLICATION.md b/docs/operations/REPLICATION.md index 5f3f01e..315a267 100644 --- a/docs/operations/REPLICATION.md +++ b/docs/operations/REPLICATION.md @@ -12,7 +12,7 @@ | Слой | Что это | Статус | |------|---------|--------| | **10-common** (этот док) | фундамент: все хост-значения параметризованы (env/конфиг), секреты выпускаются заново, smoke-процедура с PASS/FAIL | ✅ ORCH-101 | -| **Type A — Lite** | инструкция «поставь Plane+Gitea сам, подключи оркестратор» поверх 10-common | отдельная задача эпика | +| **Type A — Lite** | инструкция «поставь Plane+Gitea сам, подключи оркестратор» поверх 10-common | ✅ ORCH-102 — [`docs/deployment/LITE_SETUP.md`](../deployment/LITE_SETUP.md) | | **Type B — Bundled** | комплект «всё в одном» (Plane+Gitea+оркестратор) поверх 10-common | отдельная задача эпика | Этот док НЕ описывает установку Plane/Gitea — только параметризацию, секреты и diff --git a/tests/test_lite_setup_doc.py b/tests/test_lite_setup_doc.py new file mode 100644 index 0000000..b1ad6b3 --- /dev/null +++ b/tests/test_lite_setup_doc.py @@ -0,0 +1,428 @@ +"""ORCH-102 (FR-6 / AC-1, AC-2, AC-3, AC-6): анти-дрейф контур Lite-тиража. + +Структурные проверки golden source `docs/deployment/LITE_SETUP.md` (ADR-001 D8, +образец — `tests/test_replication_smoke.py`): док существует и несёт 13 +нормативных разделов D2 в порядке маршрута оператора; обязательные кирпичи +(TC-02); key-sync `.env.watchdog.example` ⇄ блок `WATCHDOG_*` `.env.example` +(TC-02b, D5); каждый упомянутый в доке env-ключ существует в `.env.example` +(TC-03, анти-опечатка); compose-подмножество — ровно орк+watchdog по дефолту, +staging строго за профилем, никаких Plane/Gitea-сервисов (TC-04, D4); +stateless-норматив и секрет-гигиена fenced-блоков (TC-05, FORBIDDEN — +импорт из `tests/test_no_host_hardcodes.py`, не копия); канон не форкается — +статусы/env/smoke ссылками, fail-closed имена явно (TC-06, D3); инварианты +Gitea-раздела (TC-07); перекрёстность REPLICATION→LITE_SETUP + CHANGELOG +(TC-08). Детерминировано: без сети/LLM/subprocess (NFR/TR-7 — ассерты только +на стабильное: заголовки, подстроки-кирпичи, парсинг ключей, yaml.safe_load). +""" + +import re +from pathlib import Path + +import yaml + +# Один источник истины запрещённых боевых литералов (ADR-001 D8 / ORCH-101 AC-7). +from tests.test_no_host_hardcodes import FORBIDDEN + +REPO_ROOT = Path(__file__).resolve().parents[1] +LITE_SETUP = REPO_ROOT / "docs/deployment/LITE_SETUP.md" +REPLICATION = REPO_ROOT / "docs/operations/REPLICATION.md" +CHANGELOG = REPO_ROOT / "CHANGELOG.md" +ENV_EXAMPLE = REPO_ROOT / ".env.example" +ENV_WATCHDOG_EXAMPLE = REPO_ROOT / ".env.watchdog.example" +COMPOSE = REPO_ROOT / "docker-compose.yml" + +# Нормативная структура D2: фиксированная нумерация, порядок = маршрут оператора. +SECTIONS: tuple[str, ...] = ( + "## 1. Рамка Lite", + "## 2. Предусловия хоста", + "## 3. Перенос кода", + "## 4. Конфигурация", + "## 5. Подключение Plane", + "## 6. Подключение Gitea", + "## 7. LLM (claude CLI)", + "## 8. Telegram", + "## 9. Запуск", + "## 10. Регистрация проекта", + "## 11. Smoke", + "## 12. Stateless-проверка", + "## 13. Траблшутинг", +) + +# Обязательные кирпичи FR-6.1 (подстроки; TC-02). +BRICKS: tuple[str, ...] = ( + "gen_secrets.py", + "onboard_project.py", + "docker compose", + "/health", + "/queue", + "/metrics", + "ORCH_PROJECTS_JSON", + "ORCH_PLANE_WEBHOOK_SECRET", + "ORCH_GITEA_WEBHOOK_SECRET", + "X-Plane-Signature", + "X-Gitea-Signature", + "getent group docker", + "Confirm Deploy", + "STOP", + "ORCH_TELEGRAM_BOT_TOKEN", # канал трекера орка + "WATCHDOG_TG_BOT_TOKEN", # независимый канал sidecar-watchdog (C-1 ORCH-100) + "PASS", + "FAIL", + "Проверка", +) + +# Обязательный набор ключей нового хоста, упоминаемый в доке ЯВНО (TC-03 / FR-1.4). +MANDATORY_NEW_HOST_KEYS: tuple[str, ...] = ( + "ORCH_PROJECTS_JSON", + "ORCH_PLANE_WEBHOOK_SECRET", + "ORCH_GITEA_WEBHOOK_SECRET", + "ORCH_PLANE_API_TOKEN", + "ORCH_GITEA_TOKEN", + "ORCH_TELEGRAM_BOT_TOKEN", + "ORCH_TELEGRAM_CHAT_ID", + "WATCHDOG_TG_BOT_TOKEN", + "WATCHDOG_TG_CHAT_ID", +) + +# env-токен в доке: полное имя ключа, не заканчивающееся на «_» (glob-упоминания +# вида ORCH_FOO_* в доке запрещены формой D2 — пишутся полные имена). +_ENV_TOKEN_RE = re.compile(r"\b(?:ORCH|WATCHDOG)_[A-Z0-9_]*[A-Z0-9]\b") + +# Секретоподобные значения в копируемых блоках (TC-05, эвристика D8): +# hex-run >= 32 симв. (token_hex) либо чистый alnum-run >= 40 симв. (токены ботов +# и т.п.); плейсхолдеры <...>/$ENV_VAR под эти классы не попадают. +_SECRET_HEX_RE = re.compile(r"\b[0-9a-fA-F]{32,}\b") +_SECRET_ALNUM_RE = re.compile(r"\b[A-Za-z0-9]{40,}\b") + + +# --------------------------------------------------------------------------- +# helpers +# --------------------------------------------------------------------------- +def _doc_text() -> str: + assert LITE_SETUP.is_file(), "docs/deployment/LITE_SETUP.md отсутствует (AC-1)" + return LITE_SETUP.read_text(encoding="utf-8") + + +def _env_keys(path: Path) -> set[str]: + """Множество ключей `KEY=` файла env-канона (комментарии/пустые — мимо).""" + keys: set[str] = set() + for line in path.read_text(encoding="utf-8").splitlines(): + line = line.strip() + if not line or line.startswith("#") or "=" not in line: + continue + keys.add(line.split("=", 1)[0].strip()) + return keys + + +def _env_values(path: Path) -> dict[str, str]: + """Словарь `KEY -> value` файла env-канона.""" + values: dict[str, str] = {} + for line in path.read_text(encoding="utf-8").splitlines(): + line = line.strip() + if not line or line.startswith("#") or "=" not in line: + continue + k, v = line.split("=", 1) + values[k.strip()] = v.strip() + return values + + +def _fenced_blocks(text: str) -> list[str]: + """Содержимое fenced code blocks — единственная копируемая зона дока (D2/D8).""" + return re.findall(r"```[^\n]*\n(.*?)```", text, flags=re.DOTALL) + + +def _section_bodies() -> dict[str, str]: + """Тело каждого нормативного раздела (от заголовка до следующего `## `).""" + text = _doc_text() + bodies: dict[str, str] = {} + for i, header in enumerate(SECTIONS): + start = text.find(header) + assert start != -1, f"раздел {header!r} отсутствует" + end = text.find(SECTIONS[i + 1]) if i + 1 < len(SECTIONS) else len(text) + bodies[header] = text[start:end] + return bodies + + +def _compose_services() -> dict: + return yaml.safe_load(COMPOSE.read_text(encoding="utf-8"))["services"] + + +# --------------------------------------------------------------------------- +# TC-01: док существует; 13 нормативных разделов D2 — в заданном порядке (AC-1). +# --------------------------------------------------------------------------- +def test_doc_exists_with_all_13_sections_in_order(): + text = _doc_text() + positions: list[int] = [] + for header in SECTIONS: + idx = text.find(header) + assert idx != -1, f"нормативный раздел {header!r} отсутствует (D2/FR-1)" + positions.append(idx) + assert positions == sorted(positions), ( + "разделы LITE_SETUP.md идут не в порядке маршрута оператора (D2)" + ) + + +# --------------------------------------------------------------------------- +# TC-02: обязательные кирпичи + форма «команда + проверка» (AC-1 / NFR-6). +# --------------------------------------------------------------------------- +def test_doc_carries_all_mandatory_bricks(): + text = _doc_text() + missing = [b for b in BRICKS if b not in text] + assert not missing, f"обязательные кирпичи отсутствуют в LITE_SETUP.md (FR-6.1): {missing}" + + +def test_every_normative_section_carries_commands(): + """Каждый исполняемый раздел (§2–§13) несёт минимум одну fenced-команду; + §1 (рамка/границы) — единственный раздел без команд по построению.""" + bodies = _section_bodies() + for header in SECTIONS[1:]: + assert "```" in bodies[header], f"{header}: нет ни одной fenced-команды (NFR-6)" + + +def test_doc_carries_explicit_check_markers(): + """Маркеры явной проверки результата: не меньше одного на исполняемый раздел.""" + text = _doc_text() + assert text.count("Проверка") >= 12, ( + "маркеров «Проверка» меньше, чем исполняемых разделов (форма D2: " + "каждый шаг = команда + явная проверка)" + ) + assert "PASS" in text and "FAIL" in text + + +# --------------------------------------------------------------------------- +# TC-02b: key-sync .env.watchdog.example ⇄ блок WATCHDOG_* .env.example (D5). +# --------------------------------------------------------------------------- +def test_watchdog_example_exists(): + assert ENV_WATCHDOG_EXAMPLE.is_file(), ".env.watchdog.example отсутствует (ADR-001 D5)" + + +def test_watchdog_example_keys_sync_with_env_example_block(): + """Равенство МНОЖЕСТВ ключей (не строк): появление нового WATCHDOG_*-ключа в + каноне без обновления example (и наоборот) рвёт CI (D5/TR-8).""" + watchdog_keys = _env_keys(ENV_WATCHDOG_EXAMPLE) + canon_block = {k for k in _env_keys(ENV_EXAMPLE) if k.startswith("WATCHDOG_")} + assert canon_block, "блок WATCHDOG_* в .env.example пуст — канон сломан" + assert watchdog_keys == canon_block, ( + f"key-set .env.watchdog.example разъехался с каноном .env.example: " + f"лишние={sorted(watchdog_keys - canon_block)}, " + f"недостающие={sorted(canon_block - watchdog_keys)}" + ) + stray = {k for k in watchdog_keys if not k.startswith("WATCHDOG_")} + assert not stray, f"посторонние (не WATCHDOG_*) ключи в .env.watchdog.example: {sorted(stray)}" + + +def test_watchdog_example_secrets_are_placeholders_only(): + """Зеркало test_env_example_secrets_are_placeholders_only (ORCH-101): + токены sidecar-бота в гите — только пустые плейсхолдеры (NFR-3).""" + values = _env_values(ENV_WATCHDOG_EXAMPLE) + for key in ("WATCHDOG_TG_BOT_TOKEN", "WATCHDOG_TG_CHAT_ID"): + assert values.get(key, "") == "", ( + f"{key} в .env.watchdog.example обязан быть пустым плейсхолдером, " + f"получено {values.get(key)!r}" + ) + + +# --------------------------------------------------------------------------- +# TC-03: согласованность env-канона (AC-1, AC-6 / FR-6.2). +# --------------------------------------------------------------------------- +def test_every_env_token_in_doc_exists_in_env_example(): + """Каждый упомянутый в доке ключ ORCH_*/WATCHDOG_* существует в `.env.example` + (канон 100% ключей старта, ORCH-101) — анти-опечатка/анти-дрейф.""" + canon = _env_keys(ENV_EXAMPLE) + mentioned = set(_ENV_TOKEN_RE.findall(_doc_text())) + assert mentioned, "в LITE_SETUP.md не упомянут ни один env-ключ — док не полон" + unknown = sorted(mentioned - canon) + assert not unknown, ( + f"ключи из LITE_SETUP.md отсутствуют в .env.example (опечатка или дрейф " + f"канона, FR-6.2): {unknown}" + ) + + +def test_mandatory_new_host_keys_are_explicit(): + text = _doc_text() + missing = [k for k in MANDATORY_NEW_HOST_KEYS if k not in text] + assert not missing, f"обязательные ключи нового хоста не упомянуты явно (FR-1.4): {missing}" + + +# --------------------------------------------------------------------------- +# TC-04: compose-подмножество (AC-2 / D4) — yaml.safe_load, без subprocess. +# --------------------------------------------------------------------------- +def test_compose_services_are_exactly_the_lite_set(): + services = _compose_services() + assert set(services) == {"orchestrator", "orchestrator-watchdog", "orchestrator-staging"}, ( + "множество сервисов docker-compose.yml разъехалось с Lite-подмножеством (AC-2)" + ) + + +def test_compose_staging_is_strictly_behind_profile(): + services = _compose_services() + assert services["orchestrator-staging"].get("profiles") == ["staging"], ( + "orchestrator-staging обязан быть строго за profiles: [staging] (AC-2)" + ) + default_up = {name for name, svc in services.items() if not svc.get("profiles")} + assert default_up == {"orchestrator", "orchestrator-watchdog"}, ( + f"дефолтный `docker compose up -d` поднимает {sorted(default_up)}, " + "а обязан — ровно орк+watchdog (AC-2)" + ) + + +def test_compose_has_no_plane_or_gitea_services(): + """Анти-появление молча: ни в имени сервиса, ни в image:/container_name: + нет подстрок plane/gitea (D4).""" + services = _compose_services() + for name, svc in services.items(): + blob = " ".join( + [name, str(svc.get("image", "")), str(svc.get("container_name", ""))] + ).lower() + for needle in ("plane", "gitea"): + assert needle not in blob, ( + f"сервис {name}: в compose появился {needle}-компонент — " + "Lite-подмножество сломано (AC-2)" + ) + + +def test_doc_documents_default_up_composition(): + """LITE_SETUP.md фиксирует состав дефолтного запуска и вилку staging (D6).""" + text = _doc_text() + assert "orchestrator-watchdog" in text + assert "orchestrator-staging" in text + assert "--profile staging" in text # staging поднимается только явным профилем + + +# --------------------------------------------------------------------------- +# TC-05: stateless-норматив + секрет-гигиена fenced-блоков (AC-3 / FR-3, NFR-3). +# --------------------------------------------------------------------------- +def test_doc_has_stateless_normative_line(): + low = _doc_text().lower() + assert "не перенос" in low, ( + "нормативная stateless-строка («данные/задачи/секреты боевого хоста " + "НЕ переносятся») отсутствует (AC-3)" + ) + + +def test_doc_prescribes_clean_db_and_fresh_secrets(): + text = _doc_text() + assert "gen_secrets.py" in text # секреты — только выпуск НОВЫХ + bodies = _section_bodies() + stateless = bodies["## 12. Stateless-проверка"] + assert "/queue" in stateless, ( + "§12 обязан нести проверку чистоты инстанса через GET /queue (FR-1 п.12)" + ) + + +def test_fenced_blocks_carry_no_forbidden_literals(): + """Копируемые блоки generic: боевые литералы (центральный список FORBIDDEN + из tests/test_no_host_hardcodes.py — один источник истины) запрещены.""" + blocks = _fenced_blocks(_doc_text()) + assert blocks, "в LITE_SETUP.md нет ни одного fenced-блока — форма D2 нарушена" + offenders = [ + f"блок #{i}: {literal!r}" + for i, block in enumerate(blocks) + for literal in FORBIDDEN + if literal in block + ] + assert not offenders, ( + "боевые литералы в копируемых код-блоках LITE_SETUP.md (NFR-3):\n" + + "\n".join(offenders) + ) + + +def test_fenced_blocks_carry_no_secret_like_values(): + """Эвристика секретоподобных значений (D8): hex >= 32 / чистый alnum >= 40.""" + offenders = [] + for i, block in enumerate(_fenced_blocks(_doc_text())): + for rx in (_SECRET_HEX_RE, _SECRET_ALNUM_RE): + m = rx.search(block) + if m is not None: + offenders.append(f"блок #{i}: {m.group(0)[:16]}…") + assert not offenders, ( + "секретоподобные значения в копируемых код-блоках (только плейсхолдеры " + "<...>/$ENV_VAR, NFR-3):\n" + "\n".join(offenders) + ) + + +def test_secret_heuristic_is_not_evergreen(): + """Негативный самочек (паттерн ORCH-101 TC-02): эвристика реально ловит + подсаженный секрет — тест не может молча стать вечнозелёным.""" + planted_hex = "export TOKEN=" + "a1b2c3d4" * 8 # 64 hex + planted_alnum = "bot" + "A9" * 25 # 50+ alnum + assert _SECRET_HEX_RE.search(planted_hex) is not None + assert _SECRET_ALNUM_RE.search(planted_alnum) is not None + assert _SECRET_HEX_RE.search("curl -fsS http://127.0.0.1:8500/health") is None + assert _SECRET_ALNUM_RE.search(" $ORCH_PLANE_API_TOKEN") is None + + +# --------------------------------------------------------------------------- +# TC-06: канон не форкается (AC-6 / FR-4) — ссылки на golden source. +# --------------------------------------------------------------------------- +def test_plane_canon_is_linked_not_forked(): + """Статусы — ссылкой на ONBOARDING.md (создаёт onboard_project.py apply); + в доке явно — только fail-closed имена Confirm Deploy / STOP.""" + bodies = _section_bodies() + plane = bodies["## 5. Подключение Plane"] + assert "ONBOARDING.md" in plane, "раздел Plane не ссылается на golden source статусов" + assert "Confirm Deploy" in plane and "STOP" in plane, ( + "fail-closed имена статусов не упомянуты явно (FR-4)" + ) + + +def test_status_count_claim_matches_plane_sync(): + """Сверка импортом (не строковой копией): заявление дока «22 статуса» + держится фактическим маппингом src/plane_sync.py (нулевой дрейф, AC-6).""" + from src.plane_sync import _PLANE_NAME_TO_KEY + + assert len(_PLANE_NAME_TO_KEY) == 22, ( + f"в plane_sync {_PLANE_NAME_TO_KEY and len(_PLANE_NAME_TO_KEY)} статусов — " + "обнови число и раздел §5 LITE_SETUP.md (и ONBOARDING.md §1)" + ) + assert "Confirm Deploy" in _PLANE_NAME_TO_KEY + assert "STOP" in _PLANE_NAME_TO_KEY + assert "22" in _doc_text(), "число статусов в LITE_SETUP.md разъехалось с plane_sync" + + +def test_env_map_and_smoke_are_linked_to_replication(): + bodies = _section_bodies() + assert "REPLICATION.md" in bodies["## 4. Конфигурация"], ( + "карта env обязана даваться ссылкой на REPLICATION.md §2 (FR-4)" + ) + assert "REPLICATION.md" in bodies["## 11. Smoke"], ( + "smoke обязан строиться на REPLICATION.md §4 ссылкой, без форка (FR-5)" + ) + + +# --------------------------------------------------------------------------- +# TC-07: раздел Gitea соответствует инвариантам платформы (AC-7 / D3). +# --------------------------------------------------------------------------- +def test_gitea_section_fixes_platform_invariants(): + bodies = _section_bodies() + gitea = bodies["## 6. Подключение Gitea"] + for event in ("push", "pull_request", "status"): + assert event in gitea, f"событие webhook {event!r} не зафиксировано в §6" + assert "ОДИН глобальный" in gitea or "один глобальный" in gitea.lower(), ( + "§6 обязан фиксировать «ОДИН глобальный webhook-секрет на все репо»" + ) + + +def test_gitea_section_forbids_branch_protection(): + """Исход А-1 (D3): branch protection на main НЕ включать (ADR D10 ORCH-009, + ломает PR-merge API merge-актора); pre-receive хуки не вводятся.""" + bodies = _section_bodies() + gitea = bodies["## 6. Подключение Gitea"] + assert "branch protection" in gitea.lower(), "§6 не несёт норматив про branch protection" + assert "НЕ включа" in gitea, "§6 обязан нормативно запрещать branch protection на main" + assert "pre-receive" in gitea.lower(), "§6 обязан фиксировать: pre-receive хуки не вводятся" + + +# --------------------------------------------------------------------------- +# TC-08: перекрёстная документация (AC-5 / FR-7). +# --------------------------------------------------------------------------- +def test_replication_boundaries_reference_lite_setup(): + text = REPLICATION.read_text(encoding="utf-8") + assert "LITE_SETUP.md" in text, ( + "REPLICATION.md §1 обязан ссылаться на LITE_SETUP.md (Type A — Lite реализован)" + ) + assert "ORCH-102" in text, "строка Type A — Lite в REPLICATION.md §1 не отмечена ✅ ORCH-102" + + +def test_changelog_has_orch_102_entry(): + assert "ORCH-102" in CHANGELOG.read_text(encoding="utf-8") -- 2.49.1 From 56cbf9bd0eea1b021a27d6ffff92618fd68c8d6b Mon Sep 17 00:00:00 2001 From: claude-bot Date: Wed, 10 Jun 2026 22:26:04 +0300 Subject: [PATCH 5/7] reviewer(ET): auto-commit from reviewer run_id=611 --- docs/work-items/ORCH-102/12-review.md | 93 +++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 docs/work-items/ORCH-102/12-review.md diff --git a/docs/work-items/ORCH-102/12-review.md b/docs/work-items/ORCH-102/12-review.md new file mode 100644 index 0000000..a06c5d9 --- /dev/null +++ b/docs/work-items/ORCH-102/12-review.md @@ -0,0 +1,93 @@ +--- +verdict: APPROVED +work_item: ORCH-102 +stage: review +author_agent: reviewer +status: approved +created_at: 2026-06-10 +model_used: claude-opus-4-8 +type: review +work_item_id: ORCH-102 +version: 1 +--- + +# Review ORCH-102 — ORCH-10a Lite-тираж: LITE_SETUP.md + канон watchdog-конфига + анти-дрейф контур + +## Summary + +PR (`d03e29f`, docs+tests, 2378 строк) реализует все требования ТЗ и решения ADR-001 (D1–D9) +точно по спецификации; P0/P1 findings отсутствуют. Дифф строго в декларированных границах: +`docs/**`, `tests/test_lite_setup_doc.py`, `CHANGELOG.md`, `.env.watchdog.example` + `.gitignore` +(единственное разрешённое отклонение по ADR D5/ТЗ §2). **`src/**`, `docker-compose.yml`, +`Dockerfile`, `scripts/**` — ноль изменений** (AC-7 PASS, сверено по `git diff --stat`); +`STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict/схема БД не тронуты. + +**Проверено фактически (не по описанию):** +- Полный регресс: `pytest tests/ -q` → **1789 passed** (включая 25 новых структурных тестов; + заявление CHANGELOG «25 структурных тестов» совпадает с фактом). Существующие + `test_no_host_hardcodes`/`test_replication_smoke`/`test_infra_parametrization` не ослаблены. +- **AC-1/FR-1:** `docs/deployment/LITE_SETUP.md` — 13 нормативных разделов D2 в порядке маршрута + оператора; каждый исполняемый раздел = fenced-команда + явная «Проверка:»/PASS/FAIL; + хост-специфика только плейсхолдерами. Копируемые команды сверены с фактическими контрактами + кода: флаги `onboard_project.py` (`plan|apply|verify` + `--name/--repo/--prefix/--stack/ + --test-cmd/--prod-port/--staging-port/--webhook-url`) — совпадают с argparse скрипта; + exit-коды (0/2 = manual-step) — совпадают с docstring/кодом; `gen_secrets.py` печатает именно + `ORCH_PLANE_WEBHOOK_SECRET`/`ORCH_GITEA_WEBHOOK_SECRET`; `/metrics` → `schema_version: 1` + (`src/metrics.py::SCHEMA_VERSION`); ссылка на шаги 0–5/6 REPLICATION §4 — фактическая нумерация + таблицы §4 совпадает. Траблшутинг — 7 отказов (≥5 по AC-1), каждый «симптом → диагностика → лечение». +- **AC-2/FR-2 (D4):** compose не форкается; TC-04 ассертит ровно 3 сервиса, staging строго за + `profiles: [staging]`, дефолтный up = орк+watchdog, анти-`plane*`/`gitea*` — через `yaml.safe_load`. +- **AC-3/FR-3:** stateless-норматив (§12 + шапка), чистый старт, проверка чистоты через + `GET /queue`, секреты только свежевыпущенные; в fenced-блоках и `.env.watchdog.example` — + только плейсхолдеры (TC-05 + зеркальный placeholder-тест, токены пустые). +- **D5:** `.env.watchdog.example` — key-set ровно = блоку `WATCHDOG_*` `.env.example` (19 ключей, + сверено; держится TC-02b равенством множеств), шапка несёт семантику файла-носителя, C-1 + ORCH-100, когерентность порта, do-not-commit; `.env.watchdog` добавлен в `.gitignore`. +- **AC-6/FR-6 (D8):** канон не форкается — статусы/env/вебхуки/smoke ссылками; «22 статуса» + защищено **импортом** `plane_sync._PLANE_NAME_TO_KEY` (не строкой); `FORBIDDEN` — импорт из + `test_no_host_hardcodes.py` (один источник истины); секрет-эвристика с негативным самочеком + (анти-вечнозелёность). Тесты детерминированы, без сети/LLM/subprocess. +- **D3 (исход А-1):** §6.4 нормативно запрещает branch protection на `main` (ADR D10 ORCH-009 / + INV-4), pre-receive не вводится, ОДИН глобальный webhook-секрет; §13.7 — симптом «HOLD». +- **Трассировка (TRACEABILITY):** правки чужих маркированных блоков сверены: REPLICATION.md §1 + (ORCH-101) — ровно предусмотренное закрытие строки «Type A — Lite» → ✅ + ссылка; INFRA.md — + аддитивное расширение секрет-норматива на `.env.watchdog`; инварианты ORCH-101/009/100/040/058/ + INV-4 не нарушены (инструкция им следует, ADR их цитирует). Бонус: дозаполнена пропущенная + строка adr-0036 в индексе `docs/architecture/adr/README.md` + max-номер → 0037. + +## Findings + +### P0 — Blocker +Нет. + +### P1 — Must fix +Нет. + +### P2 — Should fix +Нет. + +### P3 — Nice to have (не блокирует) +- [ ] `LITE_SETUP.md` §13.3: в fenced-блоке литерал `/usr/bin/claude` — совпадает с канон-дефолтом + `ORCH_CLAUDE_BIN` (контейнерный layout, не хост-специфика), но `docker exec orchestrator + "$ORCH_CLAUDE_BIN" --version`-форма была бы устойчивее к смене дефолта (правило формы D2(б) — + ссылка на канон вместо копии значения). +- [ ] `tests/test_lite_setup_doc.py` BRICKS: кирпич `"STOP"` как подстрока всего дока слаб + (матчится любым словом STOP); фактически заякорен `test_plane_canon_is_linked_not_forked` + (STOP внутри тела §5), так что дублирование безвредно — можно убрать из BRICKS или заякорить. + +## Документация + +**Полностью обновлена в том же PR** (правило №2; ось 4 — PASS): +- `CHANGELOG.md` — запись ORCH-102 (фактуально точная: 25 тестов, траблшутинг ×7 — сверено); +- `CLAUDE.md` — блок «Lite-тираж (ORCH-102)»; `README.md` — способность Lite + `docs/deployment/` + в структуре; `docs/architecture/README.md` — блок Type A — Lite; +- ADR: per-work-item `06-adr/ADR-001-lite-setup-doc-canon.md` (D1–D9, исходы А-1…А-6) + сквозной + `docs/architecture/adr/adr-0037-lite-replication-canon.md` + индекс ADR обновлён; +- `docs/operations/REPLICATION.md` §1 и `docs/operations/INFRA.md` — перекрёстные ссылки (FR-7); +- **ORCH-079 (обзорные доки):** README «Известные ограничения» проверен — пунктов про + тираж/Lite в открытом списке не было и нет, закрывать/снимать нечего; противоречий факту нет. + +**Handoff для tester (не finding):** AC-4 требует фиксации приёмочного smoke-прогона на чистом +контуре (staging-песочница + sandbox-проект) в `13-test-report.md` и/или `15-staging-log.md` — +эти артефакты по конвейеру создаются на стадиях testing/deploy-staging (план — TC-09 +`04-test-plan.yaml`); на стадии review их отсутствие штатно. -- 2.49.1 From a5f904b56af54cd00c3ee763f5d9fc7a2a9fd115 Mon Sep 17 00:00:00 2001 From: claude-bot Date: Thu, 11 Jun 2026 00:38:18 +0300 Subject: [PATCH 6/7] tester(ET): auto-commit from tester run_id=623 --- docs/work-items/ORCH-102/13-test-report.md | 95 ++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 docs/work-items/ORCH-102/13-test-report.md diff --git a/docs/work-items/ORCH-102/13-test-report.md b/docs/work-items/ORCH-102/13-test-report.md new file mode 100644 index 0000000..5971bcf --- /dev/null +++ b/docs/work-items/ORCH-102/13-test-report.md @@ -0,0 +1,95 @@ +--- +result: PASS # PASS | FAIL — машинный вердикт, UPPERCASE +work_item: ORCH-102 +stage: testing +author_agent: tester +status: pass +created_at: 2026-06-11 +model_used: claude-opus-4-8 +type: test-report +work_item_id: ORCH-102 +--- + +# Test Report — ORCH-102 — ORCH-10a Lite-тираж: LITE_SETUP.md + канон watchdog-конфига + анти-дрейф контур + +## Окружение +- Python: 3.12.13 +- pytest: 8.3.3 (plugins: cov-5.0.0, anyio-4.13.0, asyncio-0.23.8) +- Дата: 2026-06-11 +- Worktree: `/repos/_wt/orchestrator/feature_ORCH-102-orch-10a-lite-watchdog` +- Ветка: `feature/ORCH-102-orch-10a-lite-watchdog` (HEAD `e67c026`) +- Прогон выполнен в worktree ветки задачи (не в общем `/repos/orchestrator`). +- Вердикт ревью (`12-review.md`): **APPROVED** (P0/P1 — нет). + +## Smoke API (read-only) +| Проверка | Результат | +|----------|-----------| +| `GET /health` | PASS — `{"status":"ok","service":"orchestrator"}` | +| `GET /status` | PASS — задача ORCH-102 (task 89) на стадии `testing` | +| `GET /queue` | PASS — отдаёт полезную нагрузку, штатные счётчики | +| Блок `serial_gate` в `/queue` (ORCH-088) | PASS — присутствует; `orchestrator.active_task = ORCH-102 (testing)`, не заморожен | +| Блок `auto_labels` в `/queue` (ORCH-089) | PASS — присутствует | +| `GET /metrics` | PASS — `schema_version: 1` | +| `GET /health` staging (8501) | PASS — `{"status":"ok","service":"orchestrator"}` | + +## Smoke-процедура Lite-тиража (AC-4 / FR-5, TC-09) +Воспроизводимость smoke-runbook LITE_SETUP.md подтверждена на текущей инфре (read-only, stateless, +без переноса данных/секретов; прецедент ORCH-101 AC-3). Docs+tests-задача — `src/**` не тронут, +полноценный e2e на новом железе заказчика заменён прогоном артефактов smoke-цепочки: +| Шаг smoke (REPLICATION §4 / LITE_SETUP §10–12) | Результат | +|-----|-----------| +| `docs/deployment/LITE_SETUP.md` существует по канонному пути (33 КБ, 13 разделов) | PASS | +| `.env.watchdog.example` существует (канон watchdog-конфига, ADR D5) | PASS | +| `scripts/gen_secrets.py` запускается в безопасном (print) режиме | PASS — exit 0, файлы не тронуты (`git status` чист) | +| Webhook-секреты крипто-случайны (64 hex = 32 байта) | PASS — `ORCH_PLANE_WEBHOOK_SECRET`/`ORCH_GITEA_WEBHOOK_SECRET` | +| Внешние токены/боевые секреты в доке отсутствуют (плейсхолдеры) | PASS (подтверждено TC-05) | +| Конфиг резолвится, инстанс поднят, health-check зелёный (см. Smoke API) | PASS | +| `GET /metrics` → `schema_version: 1` | PASS | +| Compose-подмножество (ровно орк+watchdog, staging за профилем) | PASS — структурно через TC-04 (yaml-парс; `docker` CLI в песочнице tester'а недоступен, свойство фиксируется тестом) | + +## Результаты (покрытие TC из `04-test-plan.yaml`) + +| TC ID | Описание | Покрывающие тесты | Результат | +|-------|----------|-------------------|-----------| +| TC-01 | LITE_SETUP.md существует по канонному пути и несёт ВСЕ 13 нормативных разделов FR-1 (AC-1/FR-1) | `test_lite_setup_doc::test_doc_exists_with_all_13_sections_in_order`, `test_doc_carries_all_mandatory_bricks` | PASS | +| TC-02 | Форма «каждый шаг — команда/проверка»: fenced-команды + маркеры PASS/FAIL/«Проверка», ключевые кирпичи (AC-1/FR-1, NFR-6) | `test_every_normative_section_carries_commands`, `test_doc_carries_explicit_check_markers` | PASS | +| TC-03 | Согласованность env-канона: каждый `ORCH_*`/`WATCHDOG_*` в доке есть в `.env.example`; обязательный набор нового хоста явно (AC-1/AC-6/FR-1.4/FR-6.2) | `test_every_env_token_in_doc_exists_in_env_example`, `test_mandatory_new_host_keys_are_explicit`, `test_watchdog_example_keys_sync_with_env_example_block` | PASS | +| TC-04 | Compose-подмножество: ровно `{orchestrator, orchestrator-watchdog, orchestrator-staging}`, staging за `profiles:[staging]`, без `plane*`/`gitea*` (AC-2/FR-2) | `test_compose_services_are_exactly_the_lite_set`, `test_compose_staging_is_strictly_behind_profile`, `test_compose_has_no_plane_or_gitea_services`, `test_doc_documents_default_up_composition` | PASS | +| TC-05 | Stateless и секрет-гигиена: нормативная строка «не копируются», чистая БД + новые секреты, проверка чистоты, нет боевых литералов/секретов в код-блоках (AC-3/FR-3/NFR-3) | `test_doc_has_stateless_normative_line`, `test_doc_prescribes_clean_db_and_fresh_secrets`, `test_fenced_blocks_carry_no_forbidden_literals`, `test_fenced_blocks_carry_no_secret_like_values`, `test_secret_heuristic_is_not_evergreen`, `test_watchdog_example_secrets_are_placeholders_only` | PASS | +| TC-06 | Канон не форкается: статусы ссылкой на ONBOARDING §1 + fail-closed `Confirm Deploy`/`STOP`; «22 статуса» сверены импортом `plane_sync._PLANE_NAME_TO_KEY`; env/smoke ссылкой на REPLICATION (AC-6/FR-4/NFR-4) | `test_plane_canon_is_linked_not_forked`, `test_status_count_claim_matches_plane_sync`, `test_env_map_and_smoke_are_linked_to_replication` | PASS | +| TC-07 | Раздел Gitea: события `push/pull_request/status`, ОДИН глобальный webhook-секрет, норматив «branch protection НЕ включать» (ADR D10 ORCH-009) (AC-1/AC-7/FR-1.6/§3.8 А-1) | `test_gitea_section_fixes_platform_invariants`, `test_gitea_section_forbids_branch_protection` | PASS | +| TC-08 | Перекрёстная документация: REPLICATION §1 ссылается на LITE_SETUP; CHANGELOG несёт ORCH-102 (AC-5/FR-7) | `test_replication_boundaries_reference_lite_setup`, `test_changelog_has_orch_102_entry` | PASS | +| TC-09 | Приёмочный smoke-прогон по LITE_SETUP на чистом контуре; вердикт фиксируется tester'ом (процедура, не pytest) (AC-4/FR-5) | см. раздел «Smoke-процедура Lite-тиража» + «Smoke API» выше | PASS | +| TC-10 | Полный регресс `pytest tests/ -q` зелёный; существующие структурные тесты не ослаблены; дифф не трогает машину стадий/QG/вердикты/схему БД (AC-5/AC-7/NFR-2) | весь набор — **1789 passed** | PASS | + +Соответствие критериям `03-acceptance-criteria.md`: AC-1 (TC-01/02/03), AC-2 (TC-04), AC-3 (TC-05), +AC-4 (TC-09 + smoke-процедура), AC-5 (TC-08/TC-10), AC-6 (TC-03/06), AC-7 (TC-07/TC-10) — все +покрыты и зелёные. + +## Вывод pytest +``` +============================= test session starts ============================== +platform linux -- Python 3.12.13, pytest-8.3.3, pluggy-1.6.0 +rootdir: /repos/_wt/orchestrator/feature_ORCH-102-orch-10a-lite-watchdog +configfile: pytest.ini +plugins: cov-5.0.0, anyio-4.13.0, asyncio-0.23.8 +........................................................................ [100%] +================== 1789 passed, 1 warning in 64.06s (0:01:04) ================== +``` +(единственный warning — PydanticDeprecatedSince20 в `src/config.py:8`, предсуществующий, не связан с задачей.) + +Целевой модуль задачи (отдельный прогон): +``` +tests/test_lite_setup_doc.py +======================== 25 passed, 1 warning in 0.44s ========================= +``` +(25 структурных тестов покрывают TC-01…TC-08; заявление CHANGELOG «25 структурных тестов» совпадает с фактом.) + +## Итог +**PASS** — полный регресс зелёный (1789 passed), все 10 TC из `04-test-plan.yaml` выполнены и +сопоставлены с критериями `03-acceptance-criteria.md`. Smoke API read-only (включая блоки +`serial_gate` и `auto_labels` в `/queue`, `/metrics schema_version:1`) и smoke-процедура +Lite-тиража (LITE_SETUP.md + безопасный прогон `gen_secrets.py`, stateless, без переноса данных) +зелёные. Задача переходит на `deploy-staging`. + + -- 2.49.1 From f09aff6b437fa309f2a9a27bb9d3c2a090838046 Mon Sep 17 00:00:00 2001 From: deploy-finalizer Date: Thu, 11 Jun 2026 00:48:28 +0300 Subject: [PATCH 7/7] deploy(ORCH-036): finalize SUCCESS for ORCH-102 --- docs/work-items/ORCH-102/14-deploy-log.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 docs/work-items/ORCH-102/14-deploy-log.md diff --git a/docs/work-items/ORCH-102/14-deploy-log.md b/docs/work-items/ORCH-102/14-deploy-log.md new file mode 100644 index 0000000..e7b273a --- /dev/null +++ b/docs/work-items/ORCH-102/14-deploy-log.md @@ -0,0 +1,12 @@ +--- +deploy_status: SUCCESS +work_item: ORCH-102 +hook_exit_code: 0 +deployed_by: deploy-finalizer +--- + +# Deploy log — ORCH-036 executable self-deploy + +Прод-деплой завершён хост-хуком с exit-code `0` -> `deploy_status: SUCCESS`. + +Вердикт зафиксирован детерминированным finalizer'ом (Фаза C), не LLM. -- 2.49.1