From 26bdd783d6b8c17677f0d596f7f339cbbd9bba56 Mon Sep 17 00:00:00 2001 From: claude-bot Date: Wed, 10 Jun 2026 20:23:50 +0300 Subject: [PATCH] architect(ET): auto-commit from architect run_id=603 --- docs/architecture/README.md | 37 ++ ...ication-foundation-host-parametrization.md | 109 +++++ ...-001-host-parametrization-secrets-smoke.md | 374 ++++++++++++++++++ .../ORCH-101/07-infra-requirements.md | 80 ++++ .../ORCH-101/08-data-requirements.md | 32 ++ docs/work-items/ORCH-101/10-tech-risks.md | 38 ++ 6 files changed, 670 insertions(+) create mode 100644 docs/architecture/adr/adr-0036-replication-foundation-host-parametrization.md create mode 100644 docs/work-items/ORCH-101/06-adr/ADR-001-host-parametrization-secrets-smoke.md create mode 100644 docs/work-items/ORCH-101/07-infra-requirements.md create mode 100644 docs/work-items/ORCH-101/08-data-requirements.md create mode 100644 docs/work-items/ORCH-101/10-tech-risks.md diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 2af4202..753f534 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -158,6 +158,43 @@ orchestrator (каноны ORCH-52b/c/d/e); enduro-trails эталоном не `docs/work-items/ORCH-009/06-adr/ADR-001-turnkey-onboarding-kit-and-cli.md` (D1…D11), `docs/work-items/ORCH-009/07-infra-requirements.md`. +## Тираж платформы: фундамент 10-common (ORCH-101 — design) + +Фундамент эпика ORCH-10 (D5.3 «Масштаб»: раздача платформы заказчикам-тестерам, типы A Lite / +B Bundled, оба stateless). Платформа разворачивается на новой инфре **без правки кода** — только +env/конфиг; конвейер (`STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict/схема БД) — +байт-в-байт не тронут. Три слоя: + +- **Расхардкод по принципу «дефолт = боевое значение»** (kill-switch-природа: отсутствие новых + переменных = текущее поведение 1:1). Новые ключи: `ORCH_AGENT_HOME_DIR` (HOME акторских + процессов: launcher ×2 / self-deploy / post-deploy), `ORCH_AGENT_GIT_NAME` + + `ORCH_GIT_EMAIL_DOMAIN` (git-идентичности `@`; системные имена + `deploy-finalizer`/`post-deploy-monitor` — платформенные литералы), `ORCH_STAGING_PORT`. + Ссылки в Plane-комментариях — из существующих `gitea_public_url`/`gitea_owner`. + `docker-compose.yml` — интерполяция `${VAR:-default}` (карта `ORCH_HOST_*`/`ORCH_DOCKER_GID`/ + `ORCH_RUN_UID/GID`; группа ORCH-040 uid/gid/HOME/маунты двигается одними env насквозь, «МИНА 1» + `group_add` сохранена); `Dockerfile` — `ARG APP_*` (CMD не трогается: exec-form + `init: true`); + deploy-hook — `"${REPO:-…}"` + явная передача `REPO=` инвокерами. **Платформенные константы + (нормативно, НЕ конфиг):** `SELF_HOSTING_REPO="orchestrator"` (узел «empty CSV → self-hosting + only» всех `*_repos`-leaf'ов), имена сервисов/образов/профиля, контейнерный layout. + **Инвариант ORCH-058 усилен:** staging-порт конфигурируем только с fail-closed guard'ом + (`staging_port == прод-порт` → отказ freshness-пути ДО любого ssh/build, без тихого fallback). +- **Секреты нового хоста:** stdlib `scripts/gen_secrets.py` (криптослучайные webhook-секреты + `secrets.token_hex(32)`; печать по умолчанию; `--write` отказывает при существующем `.env`, + перезапись — только явный `--force`) + чек-лист внешних токенов. Норматив: боевые секреты + текущего хоста не копируются ни на одном шаге. +- **Smoke-верификация тиража:** runbook `docs/operations/REPLICATION.md` (deployment golden + source: карта env, чек-лист секретов, пошаговый smoke с PASS/FAIL — `/health` → `/queue`+ + `/metrics` → `onboard_project.py plan/apply/verify` → тестовая задача → артефакты `01–04`; + расширенно — до `done`); без нового скрипта — кирпичи уже в репо. Анти-регресс — структурный + сканер `tests/test_no_host_hardcodes.py` (запрещённые литералы в исполняемом коде + `src/**`+`watchdog/**`; `tokenize`-исключение комментариев/докстрингов; config-модули — канон + дефолтов, вне скана; allowlist пуст). + +Подробнее: [adr-0036](adr/adr-0036-replication-foundation-host-parametrization.md), детально — +`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`. + ## Конвейер и Quality Gates ``` diff --git a/docs/architecture/adr/adr-0036-replication-foundation-host-parametrization.md b/docs/architecture/adr/adr-0036-replication-foundation-host-parametrization.md new file mode 100644 index 0000000..66a19b1 --- /dev/null +++ b/docs/architecture/adr/adr-0036-replication-foundation-host-parametrization.md @@ -0,0 +1,109 @@ +--- +work_item: ORCH-101 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-10 +model_used: claude-opus-4-8 +--- + +# adr-0036: Фундамент тиража платформы — параметризация хоста, секреты, smoke (ORCH-101, 10-common) + +## Статус +Proposed + +## Контекст + +Эпик ORCH-10 (D5.3 «Масштаб») — тираж платформы для заказчиков-тестеров двумя типами (A Lite / +B Bundled), оба stateless. Платформа была фактически прибита к хосту `mva154`: четыре места в +`src/**` обходили конфиг (внешний Gitea-URL в `plane_sync`, HOME + git-идентичности акторов в +`launcher`/`self_deploy`/`post_deploy`), `docker-compose.yml`/`Dockerfile`/deploy-hook несли +литералы путей/uid/gid/портов; механизма выпуска нового комплекта секретов и процедуры верификации +развёрнутой копии не существовало. ORCH-101 (10-common) — общий фундамент обоих типов тиража. + +Это сквозное решение: оно задаёт **платформенные конвенции тиража** и трогает блоки, помеченные +маркерами ORCH-036/ORCH-040/ORCH-058 (по `docs/_standards/TRACEABILITY.md` — сводный ADR вместо +архео-перечисления). Детальный пакет решений (D1…D10) — work-item ADR: +`docs/work-items/ORCH-101/06-adr/ADR-001-host-parametrization-secrets-smoke.md`. + +## Решение + +**Принцип: «дефолт = боевое значение».** Каждое хост-специфичное значение читается из конфига +(`Settings` env `ORCH_*` / compose-интерполяция `${VAR:-default}` / Dockerfile `ARG` / +shell-default хука) с дефолтом, равным текущему боевому значению. Отсутствие новых переменных = +байт-в-байт текущее поведение (kill-switch-природа; отдельный функциональный флаг не вводится). +`src/config.py` и `watchdog/config.py` — единственные легитимные места хост-литералов в коде. + +**Новые конфиг-ключи:** `agent_home_dir` (`ORCH_AGENT_HOME_DIR`, `/home/slin`) — HOME всех +акторских процессов; `agent_git_name` (`claude-bot`) + `git_email_domain` (`mva154.local`) — +git-идентичности (`@`; системные акторы `deploy-finalizer`/`post-deploy-monitor` — +платформенные литералы); `staging_port` (`ORCH_STAGING_PORT`, `8501`). Ссылки в Plane-комментариях — +из существующих `gitea_public_url`/`gitea_owner`. Compose-слой — карта `ORCH_HOST_*`/ +`ORCH_DOCKER_GID`/`ORCH_RUN_UID/GID` + реюз `ORCH_DEPLOY_*`; порт прод/стейджинг — явные `command:` +с `${ORCH_DEPLOY_PROD_TARGET_PORT:-8500}` / `${ORCH_STAGING_PORT:-8501}` (CMD образа не трогается — +exec-form + `init: true` сохранены). + +**Платформенные конвенции тиража (нормативно):** +1. **`SELF_HOSTING_REPO = "orchestrator"` — константа, не конфиг.** На ней «empty CSV → + self-hosting only» всех `*_repos`-leaf'ов; конфигурируемость превращала бы опечатку env в + активацию деплой-машинерии на чужом репо или тихое выключение всех self-гейтов. Репо платформы + в тираже обязан называться `orchestrator` (REPLICATION.md). +2. **Имена compose-сервисов/контейнеров/образов, профиль `staging`, `network_mode: host`, + контейнерный layout (`/app/data`, `/repos`, `/opt/claude-code`)** — конвенции, не переменные + (для образов истина уже в конфиге `deploy_prod_*_image`). +3. **Staging-порт конфигурируем ТОЛЬКО с fail-closed guard'ом** (усиление инварианта ORCH-058 + AC-9): freshness-путь отказывает ДО любого ssh/build при + `staging_port == deploy_prod_target_port` — без тихого fallback. Explicit-pass таргета хуку + (`TARGET_PORT=` и др.) сохранён; добавлена явная передача `REPO=` обоими инвокерами хука + (его строка 38 становится `"${REPO:-…}"` — exit-контракт 0/1/2 ORCH-036 не тронут). +4. **Группа ORCH-040 неделима:** uid/gid/HOME/маунт-таргеты/`useradd` управляются одними env + насквозь (`ORCH_RUN_UID/GID`, `ORCH_AGENT_HOME_DIR` → compose `user:`/таргеты/`build.args + APP_*`); `group_add` docker-gid («МИНА 1») не удаляется — литерал станет + `${ORCH_DOCKER_GID:-999}`. + +**Секреты нового хоста:** stdlib-скрипт `scripts/gen_secrets.py` — криптослучайные webhook-секреты +(`secrets.token_hex(32)`), печать по умолчанию, `--write` отказывает при существующем `.env` +(перезапись — только явный `--force`); внешние токены (Plane/Gitea/Telegram/watchdog) — по +чек-листу. Норматив: **боевые секреты текущего хоста не копируются ни на одном шаге**. + +**Smoke-верификация тиража:** runbook `docs/operations/REPLICATION.md` (deployment golden source: +карта env, чек-лист секретов, пошаговый smoke с PASS/FAIL: `compose config` → `/health` → +`/queue`+`/metrics` → `onboard_project.py plan/apply/verify` → тестовая задача → артефакты `01–04` +в ветке; расширенно — до `done`; границы 10-common vs Lite vs Bundled). Нового smoke-скрипта нет — +шаги собраны из существующих кирпичей. + +**Анти-регресс (постоянная CI-гарантия):** структурный сканер `tests/test_no_host_hardcodes.py` — +запрещённые литералы (`82.22.50.71`, `/home/slin`, `mva154`, `duckdns`; список централизован) в +исполняемом коде `src/**`+`watchdog/**`; `tokenize`-исключение комментариев/докстрингов; +структурное исключение двух config-модулей (канон дефолтов); allowlist пуст; негативная +самопроверка. + +### Что НЕ меняется +`STAGE_TRANSITIONS`, состав `QG_CHECKS`, семантика `check_*`, machine-verdict ключи, схема БД — +байт-в-байт; значения существующих конфиг-дефолтов; INV-4; прод-контейнер в рамках задачи не +рестартуется (правки compose/Dockerfile инертны до штатного деплоя через staging 8501 → +`Confirm Deploy`). + +## Альтернативы +- **`ORCH_SELF_HOSTING_REPO` конфигом** — отвергнуто: узел безопасности; опечатка = групповой риск. +- **Staging-порт константой** — отвергнуто: compose-порт параметризуется (AC-6), константа дала бы + рассинхрон слоёв; пара «ключ + guard» строго сильнее. +- **Smoke-скрипт-обвязка / генератор в `onboard_project.py`** — отвергнуто: лишняя поверхность; + разные жизненные циклы (онбординг проекта ≠ provisioning хоста). + +## Последствия +- Платформа разворачивается на чужой инфре env-конфигурацией; критический путь ORCH-10 разблокирован + (Lite/Bundled строятся поверх REPLICATION.md). +- Инвариант ORCH-058 переходит из «подразумеваемого константой» в исполняемый guard; возврат + хост-хардкода ломает CI структурно. +- Цена: ~13 новых env-имён (на текущем хосте настраивать нечего — дефолты боевые) и правило + «интерполяция читает `.env`/shell, не `env_file`» (зафиксировано в REPLICATION.md). +- Откат: не задавать переменные (дефолты = прежнее поведение); полный — revert PR (без миграций). + +## Связи +adr-0005 (ORCH-040 — uid/HOME/«МИНА 1»; группа становится параметризуемой, инвариант сохранён), +adr-0008 (ORCH-058 — INV-FRESH/AC-9; guard усиливает), adr-0007 (ORCH-036 — exit-контракт хука +не тронут), adr-0035 (ORCH-009 — onboarding переиспользуется smoke-процедурой; kit не форкается), +adr-0001 (`is_self_hosting_repo` — конвенция имени закреплена). Детально — +`docs/work-items/ORCH-101/06-adr/ADR-001-host-parametrization-secrets-smoke.md` (D1…D10), +`07-infra-requirements.md`, `10-tech-risks.md`. diff --git a/docs/work-items/ORCH-101/06-adr/ADR-001-host-parametrization-secrets-smoke.md b/docs/work-items/ORCH-101/06-adr/ADR-001-host-parametrization-secrets-smoke.md new file mode 100644 index 0000000..9aa9f13 --- /dev/null +++ b/docs/work-items/ORCH-101/06-adr/ADR-001-host-parametrization-secrets-smoke.md @@ -0,0 +1,374 @@ +--- +work_item: ORCH-101 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-10 +model_used: claude-opus-4-8 +--- + +# ADR-001: Параметризация хоста + секреты нового хоста + smoke-верификация (фундамент тиража 10-common) + +Work Item: **ORCH-101** — ORCH-10-common: расхардкод + секреты + smoke +Стадия: **architecture** +Сквозная регистрация: **`docs/architecture/adr/adr-0036-replication-foundation-host-parametrization.md`** +(решение кросс-каттинговое: задаёт платформенные конвенции тиража и трогает блоки с маркерами +ORCH-036/040/058 — по `docs/_standards/TRACEABILITY.md` агрегируется сводным сквозным ADR). + +## Статус +Proposed + +## Контекст + +Эпик ORCH-10 (D5.3 «Масштаб») требует разворачивать платформу на чужой инфре **без правки кода** — +двумя типами тиража (A Lite / B Bundled), оба stateless. Сегодня платформа прибита к `mva154`: +часть значений **обходит конфиг**. Аудит стадии analysis (нормативный реестр — `02-trz.md` §3.1) +перепроверен мной по коду ветки (`grep` всех запрещённых классов по `src/**`+`watchdog/**`): + +- **Код-блокеры ровно четыре:** A1 `plane_sync.py:1064` (`gitea_base = "http://git.mva154.duckdns.org"` + + owner `admin` в ссылках), A2 `agents/launcher.py:594,825` (HOME + git-идентичность ×2 места), + A3 `self_deploy.py:332–336`, A4 `post_deploy.py:575–579` (то же у finalizer/monitor). +- **Все остальные вхождения** `82.22.50.71|/home/slin|mva154|duckdns` в `src/**`/`watchdog/**` — + комментарии/докстринги (`disk_watchdog.py:3,80`, `build_cache_pruner.py:3`, `fs_normalize.py:7`, + `config.py:469`) либо **легитимные конфиг-дефолты** (`config.py:48,201` — реестр E, BR-1). +- A7 (`fs_normalize.py::healing_command`) **уже config-backed в основном пути** (строит из + `_resolve_target_uid`/`settings.worktrees_dir`); литерал остался только в `except`-ветке + never-raise (см. D10). +- Инфра-файлы: `docker-compose.yml` (реестр B1–B6), `Dockerfile` (C1–C2), + `scripts/orchestrator-deploy-hook.sh:38` (D1 — единственная непараметризованная строка скрипта; + критично: хук **безусловно перезаписывает** `REPO=`, поэтому даже корректный env инвокера сегодня + игнорируется). +- Секретов «для нового хоста» нет (общий webhook-secret = чужой хост шлёт нам валидные вебхуки); + smoke-процедуры тиража нет. + +Сопутствующие инварианты, которые НЕЛЬЗЯ ослабить (правило №9, ADR прочитаны): +**ORCH-040** (adr-0005: uid 1000 + `group_add: ["999"]` «МИНА 1» + HOME согласован с маунтами), +**ORCH-058** (adr-0008: freshness-путь целится ТОЛЬКО в staging, explicit-pass таргета, INV-FRESH), +**ORCH-036** (adr-0007: exit-code контракт хука 0/1/2, detached Phase B), **INV-4** (мерж только +через Gitea PR-merge API). + +## Решение + +### Сводка + +Три слоя одного фундамента. (1) **Расхардкод**: четыре код-блокера переводятся на `Settings` +(три новых ключа + два существующих), инфра-файлы — на compose-интерполяцию/`ARG`/env-override; +**каждый дефолт равен боевому значению** → отсутствие новых переменных = байт-в-байт текущее +поведение (kill-switch-природа, NFR-2; отдельный флаг не вводится). (2) **Секреты**: новый +stdlib-скрипт `scripts/gen_secrets.py` (криптослучайные webhook-секреты, печать по умолчанию, +никогда не перезаписывает `.env` молча) + чек-лист внешних токенов. (3) **Smoke**: чистый runbook +`docs/operations/REPLICATION.md` из существующих кирпичей (`/health`, `/queue`, `/metrics`, +`onboard_project.py`, sandbox-задача), без нового скрипта. Анти-регресс — структурный сканер +`tests/test_no_host_hardcodes.py`. Конвейер (`STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/ +machine-verdict/схема БД) — байт-в-байт не тронут (NFR-6). + +### D1 — Принцип параметризации: «дефолт = боевое значение», механизм по слоям + +| Слой | Механизм | Канон дефолта | +|------|----------|---------------| +| `src/**`, `watchdog/**` | ключи `Settings` (env `ORCH_*`) / `watchdog.Config` (`WATCHDOG_*`) | `src/config.py` / `watchdog/config.py` — **единственные легитимные места** хост-литералов в коде (BR-1) | +| `docker-compose.yml` | интерполяция `${VAR:-default}` | дефолт в самом файле = текущее значение | +| `Dockerfile` | build `ARG` (+ wiring через compose `build.args`) | дефолт `ARG` = текущее значение | +| `scripts/orchestrator-deploy-hook.sh` | `"${VAR:-default}"` (паттерн остальных переменных хука) | дефолт = текущее значение | + +**Правило одного имени:** если значение нужно и контейнеру (pydantic), и compose-интерполяции — +используется **одно** env-имя (например `ORCH_AGENT_HOME_DIR`, `ORCH_STAGING_PORT`): pydantic +читает его из `env_file`, compose — из `.env`/shell. Два имени для одного факта запрещены. + +**Источник интерполяции (важно, фиксируется в REPLICATION.md):** compose резолвит `${VAR}` из +`.env` проекта/shell-окружения, **НЕ** из `env_file` сервиса — `.env.staging` на интерполяцию не +влияет. Для single-host тиража это штатно: интерполяционные значения живут в `.env`. + +Привязка: BR-1, BR-2, BR-5, NFR-2 / FR-1, FR-2, FR-3. Проверка: AC-1, AC-2, AC-6 (TC-01…TC-08). + +### D2 — Новые `Settings`-ключи и группировка акторских env (вопрос А-5) + +Выбран вариант **«единый HOME + общий email-домен + одно агентское имя»** (3 ключа), против +6+ per-actor ключей: + +| Ключ | env | Дефолт | Потребители | +|------|-----|--------|-------------| +| `agent_home_dir` | `ORCH_AGENT_HOME_DIR` | `/home/slin` | `HOME` всех 4 акторских env-словарей: `launcher` (×2 места — Popen агента и git commit/push), `self_deploy.write_deploy_log`, `post_deploy.write_post_deploy_log`; + compose mount-таргеты и `ARG APP_HOME` (D5/D6) | +| `agent_git_name` | `ORCH_AGENT_GIT_NAME` | `claude-bot` | `GIT_AUTHOR/COMMITTER_NAME` агентов в `launcher` (×2) — customer-visible идентичность коммитов | +| `git_email_domain` | `ORCH_GIT_EMAIL_DOMAIN` | `mva154.local` | домен email всех трёх акторов | + +**Контракт идентичностей:** email строится как `f"{name}@{settings.git_email_domain}"`, где +`name` = `settings.agent_git_name` для агентов (launcher) и **платформенные литералы** +`deploy-finalizer` / `post-deploy-monitor` для системных акторов (`self_deploy` / `post_deploy`) — +имена системных акторов не хост-специфичны, различимость их коммитов в истории ценна, ключи на них +не заводятся. Дефолтные итоговые значения = сегодняшним байт-в-байт: `claude-bot@mva154.local`, +`deploy-finalizer@mva154.local`, `post-deploy-monitor@mva154.local` (BR-5). + +**A1 (`plane_sync.notify_stage_change`) — новых ключей НЕ требует:** база ссылок — +`settings.gitea_public_url or settings.gitea_url` (точно та же fallback-семантика, что у +существующих потребителей `notifications.py:901` и `usage.py:457,662`), owner — +`settings.gitea_owner` (заменяет литерал `admin` в путях Branch/PR). + +Каждый новый ключ получает описательный комментарий в `config.py` (по образцу соседних блоков), +строку в `.env.example` и в карте env `INFRA.md`. Контракт FR-2 после изменения: **ни один из +акторов не содержит литералов `/home/slin` / `mva154` в исполняемом коде** (TC-03…TC-05). + +### D3 — Вопрос А-2: `SELF_HOSTING_REPO = "orchestrator"` остаётся платформенной константой + +**Решение: НЕ конфигурируем.** Имя self-hosting репо — **нормативная конвенция тиража**: «репо +платформы в любом тираже обязан называться `orchestrator`» (фиксируется в REPLICATION.md §границы ++ чек-лист). Обоснование: + +1. **Это узел безопасности, а не хост-значение.** На `is_self_hosting_repo` завязана семантика + «empty CSV → self-hosting only» **всех** `*_repos`-leaf'ов (merge-gate, image-freshness, + security, coverage, serial-gate freeze, fs-normalize, auto-labels, bug-fast-track, deploy-guard…). + Опечатка в гипотетическом `ORCH_SELF_HOSTING_REPO` либо **активирует деплой-машинерию на чужом + репо** (групповой риск), либо **молча выключает все self-гейты** на своём (класс «гейт тихо + исчез» — худший отказ по урокам ORCH-058). Константа делает оба отказа структурно невозможными. +2. **Цена конвенции — ноль.** Тираж stateless (решение Славы 10.06): репо платформы создаётся + заново на целевой инфре (Type A — по инструкции Lite, Type B — в комплекте) — его имя полностью + под контролем оператора. Конфигурируемость не покупает ни одного сценария, который конвенция не + даёт бесплатно. +3. Расширяемость не теряется: если будущий тираж потребует иного имени — отдельная задача с + guard'ами; этот ADR — зафиксированное место, откуда она стартует. + +Привязка: AC-1 (вариант «обоснованы в ADR задачи как платформенные константы»). Анти-дрейф: тест +фиксирует константу (см. D10/TC-11-паттерн). + +### D4 — Вопрос А-1: staging-порт конфигурируем С fail-closed guard (инвариант ORCH-058 усилен) + +**Решение: конфигурируем порт, НЕ конфигурируем имена.** Новый ключ: + +- `staging_port: int = 8501` (env **`ORCH_STAGING_PORT`**) — заменяет модульную константу + `image_freshness._STAGING_PORT`; то же env-имя интерполируется в `command:` staging-сервиса + compose (`${ORCH_STAGING_PORT:-8501}`, реестр B6) → обе точки читают один факт (D1). +- `_STAGING_SERVICE` / `_STAGING_COMPOSE_PROFILE` (`orchestrator-staging` / `staging`) — + **остаются константами**: имена сервисов/профиля нашего же compose-файла — платформенная + конвенция (логика D3); их разъезд с compose ломал бы rebuild внутри одного репо без выгоды. + +**Guard (ядро решения, NFR-4 / Р-2):** в начале freshness-пути (`check_staging_image_fresh`, +ДО любого ssh/build/recreate) — проверка +`settings.staging_port == settings.deploy_prod_target_port` → **отказ fail-closed**: +`(False, "misconfiguration: ORCH_STAGING_PORT == prod target port (ORCH-058 AC-9) — staging rebuild refused")` ++ best-effort Telegram-алерт. **Без тихого fallback на 8501** — молчаливая подмена порта хуже +громкого отказа (оператор обязан починить env). Дисциплина explicit-pass ORCH-058 сохраняется: +`TARGET_PORT=` по-прежнему передаётся хуку явно (`image_freshness.py:272`), источник теперь — один +валидируемый конфиг-ключ вместо литерала. Инвариант «freshness-путь никогда не целится в прод» +из подразумеваемого константой становится **исполняемым** (guard) — усиление, не ослабление. + +Примечание: при изменённом `ORCH_STAGING_PORT` ручной запуск хука `--build-staging` без env-прefix +использует staging-дефолты хука (8501) — это документируется в REPLICATION.md (ручные запуски — +с явным `TARGET_PORT=`); wired-путь (через `image_freshness`) всегда передаёт порт явно. + +Привязка: FR-1 A5, AC-8, TC-11. + +### D5 — Вопрос А-3: CMD Dockerfile остаётся `8500`; параметризация порта — на слое compose + +**Решение: `CMD` не трогаем** (exec-form, `--port 8500` — документированный дефолт образа): + +- `ARG` не подставляется в рантайм-CMD; shell-form CMD (`sh -c "… ${PORT}"`) менял бы + PID-1/сигнальную семантику — пара «`init: true` + exec-form» выверена (B-2, зомби-репарентинг + поддерева claude/node) и трогать её ради порта — риск без выгоды. +- Порт конфигурируется там, где уже доказанно работает (staging так живёт с ORCH-31): **оба** + compose-сервиса получают явный `command:`: прод — + `["uvicorn","src.main:app","--host","0.0.0.0","--port","${ORCH_DEPLOY_PROD_TARGET_PORT:-8500}"]`, + staging — то же с `${ORCH_STAGING_PORT:-8501}`. **Реюз существующего env-имени** + `ORCH_DEPLOY_PROD_TARGET_PORT` (ключ `deploy_prod_target_port: 8500` уже описывает прод-порт для + деплой-пути) — вторая «истина» о прод-порте не вводится. Дефолтный резолв = байт-в-байт текущему + CMD → эффективная конфигурация 1:1 (AC-2; TC-06 сверяет резолв по значениям). + +**C1 (`useradd`):** `ARG APP_UID=1000 / APP_GID=1000 / APP_USER=slin / APP_HOME=/home/slin` в +`Dockerfile`; compose `build.args` обоих сервисов прокидывают их из тех же env, что и рантайм: +`APP_UID: ${ORCH_RUN_UID:-1000}`, `APP_GID: ${ORCH_RUN_GID:-1000}`, +`APP_HOME: ${ORCH_AGENT_HOME_DIR:-/home/slin}` → uid/gid/HOME двигаются **одной согласованной +группой** (инвариант ORCH-040, FR-3). `APP_USER` — косметика passwd-записи (важен факт записи для +`getpwuid`/ssh, ORCH-058 Dockerfile:38, не имя), дефолт `slin`. + +Привязка: FR-1 C1–C2, §3.4 А-3, AC-6, TC-07. + +### D6 — Карта compose-интерполяции (реестр B) и согласованная группа ORCH-040 + +Полная карта переменных `docker-compose.yml` (дефолты = текущим значениям; все три сервиса): + +| Переменная | Дефолт | Закрывает | +|---|---|---| +| `ORCH_HOST_REPOS_DIR` *(реюз)* | `/home/slin/repos` | B1 volumes ×3 (`:/repos`, у watchdog `:ro`) + environment ×2 (`ORCH_HOST_REPOS_DIR=` прокидывается тем же значением) | +| `ORCH_HOST_CLAUDE_DIR` | `/home/slin/.claude` | B1 (source маунта) | +| `ORCH_HOST_CLAUDE_JSON` | `/home/slin/.claude.json` | B1 (source, `:ro`) | +| `ORCH_HOST_SSH_DIR` | `/home/slin/.orchestrator-ssh` | B1 (source, `:ro`) | +| `ORCH_AGENT_HOME_DIR` *(= Settings-ключ D2)* | `/home/slin` | **таргеты** маунтов `.claude`/`.claude.json`/`.ssh` (`…:${ORCH_AGENT_HOME_DIR:-/home/slin}/.claude` и т.д.) + `build.args APP_HOME` | +| `ORCH_HOST_CLAUDE_CODE_DIR` | `/usr/lib/node_modules/@anthropic-ai/claude-code` | B2 (`:/opt/claude-code:ro`) | +| `ORCH_HOST_NODE_BIN` | `/usr/bin/node` | B2 (`:/usr/bin/node:ro`) | +| `ORCH_DOCKER_GID` | `999` | B3 `group_add` ×3 — **«МИНА 1» НЕ удаляется**, меняется только литерал на `${ORCH_DOCKER_GID:-999}` | +| `ORCH_RUN_UID` / `ORCH_RUN_GID` | `1000` / `1000` | B4 `user:` ×2 + `build.args APP_UID/APP_GID` | +| `ORCH_DEPLOY_SSH_USER` *(реюз)* | `slin` | B5: `ORCH_DEPLOY_SSH_USER=`, `DEPLOY_SSH_USER=` (legacy enduro — то же значение через `${ORCH_DEPLOY_SSH_USER:-slin}`) | +| `ORCH_DEPLOY_HOST_REPO_PATH` *(реюз)* | `/home/slin/repos/orchestrator` | B5 environment | +| `DEPLOY_HOOK_SCRIPT` *(legacy)* | `/home/slin/bin/enduro-deploy-hook.sh` | B5 ×2 (`${DEPLOY_HOOK_SCRIPT:-…}`) | +| `ORCH_STAGING_PORT` *(= Settings-ключ D4)* | `8501` | B6 `command:` staging | +| `ORCH_DEPLOY_PROD_TARGET_PORT` *(реюз)* | `8500` | `command:` prod (D5) | + +Не параметризуются (зафиксировано): контейнерные пути (`/app/data`, `/repos`, `/opt/claude-code`, +`/var/run/docker.sock`) — конвенция layout'а контейнера, не хост-специфика; +`DEPLOY_SSH_HOST/ORCH_DEPLOY_SSH_HOST=127.0.0.1` — loopback при `network_mode: host`, валиден на +любом single-host; имена сервисов/контейнеров/образов — платформенные константы (D3/D4; для образов +истина уже в конфиге: `deploy_prod_source_image`/`deploy_prod_target_image`); `network_mode: host`, +`init: true`, профиль `staging` — архитектурные решения, не значения. + +Группа ORCH-040 после изменения: `ORCH_RUN_UID/GID` + `ORCH_AGENT_HOME_DIR` + source-переменные +маунтов меняются согласованно; при дефолтах резолв эквивалентен текущему файлу (TC-06). + +### D7 — Deploy-hook: env-override `REPO` + явная передача от инвокеров + +1. `scripts/orchestrator-deploy-hook.sh:38`: `REPO=/home/slin/repos/orchestrator` → + `REPO="${REPO:-/home/slin/repos/orchestrator}"` (паттерн остальных переменных хука; D1 реестра). +2. **Оба инвокера передают `REPO` явно** (иначе на новом хосте env-override мёртв — сейчас хук + безусловно перезаписывает значение): `self_deploy.build_deploy_command` (prod env-прefix) и + `image_freshness` (`env_assignments`, строки ~268–275) добавляют + `REPO={shlex.quote(settings.deploy_host_repo_path)}` — тот же источник, которым инвокеры уже + делают `cd` (`image_freshness.py:277`). Конфиг становится единственной истиной на wired-пути; + дефолт хука сохраняет ручные операторские запуски на текущем хосте. + +**Инварианты не тронуты:** exit-code контракт хука (0/1/2, ORCH-036), шаги `--deploy`/`--rollback`/ +`--build-staging`, provenance-guard `EXPECTED_REVISION` (ORCH-058 Strategy B) — добавляется ровно +одно env-присваивание в префикс команды. Привязка: FR-1 D1, AC-6, TC-08. + +### D8 — Вопрос А-4 (секреты): отдельный stdlib-скрипт `scripts/gen_secrets.py` + +**Форма: новый самостоятельный скрипт** (НЕ режим `onboard_project.py`: онбординг подключает проект +к **живой** платформе, генерация секретов — provisioning **нового хоста**; это разные жизненные +циклы и разные операторы, смешение связало бы независимые сценарии и раздуло CLI ORCH-009). + +Контракт (BR-3 / FR-4 / NFR-3 / AC-5, TC-09): + +- **stdlib-only** (`secrets`, `argparse`); генерирует `ORCH_PLANE_WEBHOOK_SECRET`, + `ORCH_GITEA_WEBHOOK_SECRET` через `secrets.token_hex(32)` (32 байта энтропии, 64 hex-символа; + повторный запуск — другие значения). +- **Режим по умолчанию — печать в stdout** (`.env`-фрагмент: сгенерированные webhook-секреты + + плейсхолдеры внешних токенов + указатель на чек-лист); файлы не трогаются. +- `--write [PATH=.env]`: **существующий файл → отказ с exit≠0 и внятным сообщением**; перезапись — + только явный `--force` (AC-5 «отказ/явное подтверждение»). Никогда не перезаписывает молча. +- Состав ключей вывода согласован с `.env.example` (TC-09 сверяет программно). +- **Инвентаризация секретов** (фиксация аудита FR-4.1): генерируемые локально — + `ORCH_PLANE_WEBHOOK_SECRET`, `ORCH_GITEA_WEBHOOK_SECRET`; выпускаемые внешними системами (только + чек-лист REPLICATION.md: где выпустить → куда вписать → как проверить) — `ORCH_PLANE_API_TOKEN`, + `ORCH_PLANE_BOT_*` (7, опциональны — fallback на API-токен), `ORCH_GITEA_TOKEN`, + `ORCH_TELEGRAM_BOT_TOKEN` (+несекретный `ORCH_TELEGRAM_CHAT_ID`), sidecar + `WATCHDOG_TG_BOT_TOKEN`/`WATCHDOG_TG_CHAT_ID` (ORCH-100, независимый канал). Нормативная строка: + **«боевые секреты текущего хоста не копируются ни на одном шаге»**. +- `.env.example` дополняется до 100% обязательных ключей старта (включая новые D2/D4/D6); + секретные значения — только плейсхолдеры; `.env.staging.example` согласуется. + +### D9 — Вопрос А-4 (smoke): чистый runbook без нового скрипта + +**Форма: документированная процедура** `docs/operations/REPLICATION.md` (имя из ТЗ принято), +собранная из **существующих кирпичей** — нового smoke-скрипта **не вводим**: каждый шаг уже имеет +машинную команду с однозначным исходом; обвязка добавила бы поверхность сопровождения и LLM/сетевые +зависимости без новой гарантии (AC-3 допускает «и/или скрипт»; TC-10 — «если введён»). + +Скелет процедуры (developer материализует; каждый шаг — явные PASS/FAIL): + +| Шаг | Команда/кирпич | PASS | +|---|---|---| +| 0. Конфиг резолвится | `docker compose config` | резолв без ошибок/未-переменных | +| 1. Инстанс жив | `curl -fsS http://127.0.0.1:/health` | HTTP 200 | +| 2. Контракты отвечают | `GET /queue`, `GET /metrics` | JSON, штатные блоки, `schema_version: 1` | +| 3. Тестовый проект | `scripts/onboard_project.py plan` → `apply` → `verify` (sandbox) | `verify` зелёный | +| 4. Тестовая задача | создать issue в Plane → статус «To Analyse» | задача в БД, analyst-job в `GET /queue` | +| 5. **Минимальный сигнал «конвейер доехал»** | дождаться окончания `analysis` | артефакты `01–04` в ветке задачи (`git ls-tree origin/ docs/work-items//`) | +| 6. Расширенный режим (опционально) | Approved → … → Confirm Deploy | задача дошла до `done` | + +Итог — однозначный вердикт PASS/FAIL; при FAIL — что собрать (логи контейнера, снапшот `/queue`). +Stateless: ни один шаг не предполагает перенос данных/БД/секретов с боевого хоста. +**Приёмка воспроизводимости (AC-3):** один прогон на текущей инфре — staging-песочница 8501 + +sandbox-проект (исполняет tester, фиксация в `13-test-report.md`/`15-staging-log.md`). +Границы «10-common vs Lite vs Bundled» — отдельный раздел REPLICATION.md (анти-скоуп-крип Р-5). + +### D10 — Анти-регресс сканер: механика исключений (NFR-5) + +`tests/test_no_host_hardcodes.py` (образец — `tests/test_agent_prompts_canon.py`): + +- **Список запрещённых литералов централизован в тесте:** + `FORBIDDEN = ("82.22.50.71", "/home/slin", "mva154", "duckdns")` — единственная точка правки. +- **Зона скана:** `src/**/*.py` + `watchdog/**/*.py`. Вне зоны: `tests/**`, `docs/**`, `scripts/**` + (deploy-hook несёт легитимный shell-default D7), `.env*`. +- **Структурное исключение — `src/config.py` и `watchdog/config.py` целиком:** это канонические + места дефолтов (BR-1), и их дефолты **обязаны** нести боевые значения (BR-5: `/home/slin`, + `mva154.local`) — сканировать их значило бы держать вечно непустой allowlist. Исключение — + правило теста с комментарием-обоснованием, не allowlist-запись. +- **Исключение комментариев/докстрингов** — через `tokenize` (надёжнее построчных regex: судит + токены `COMMENT`/`STRING`-докстринги, а не текст; детерминирован — NFR-5). +- **Allowlist-механизм** (`{(file, literal): "обоснование"}`) существует и **пуст на сдаче** + (после D2/D7 код-блокеров не остаётся; `fs_normalize.healing_command` except-ветка + (`/repos/_wt`, `1000:1000`) запрещённых литералов **не содержит** и остаётся как never-raise + floor — главный путь уже строит подсказку из settings, отдельной правки A7 не требуется). +- **Негативная самопроверка (TC-02):** сканер прогоняется по синтетическому фрагменту с + подсаженным литералом и обязан его поймать (тест не вечно-зелёный). + +### Что НЕ меняется (граница решения) + +- `STAGE_TRANSITIONS`, состав `QG_CHECKS`, семантика `check_*`, machine-verdict ключи, схема БД — + байт-в-байт (NFR-6); новые тесты входят в существующие гейты (`check_ci_green`/merge-gate re-test) + автоматически. +- Значения существующих дефолтов реестра E (`02-trz.md` §3.1) — не меняются (BR-5). +- A8 (`disk_watchdog` fallback `["/repos","/app/data"]`) — config-backed зеркало, остаётся как есть + (синхронность с конфиг-дефолтом фиксирует существующий тест-ландшафт; вводить «одну точку истины» + ради неблокера — лишний диф). +- A9 (`projects._DEFAULT_PROJECTS`) — документированный fallback, не трогаем; чек-лист REPLICATION.md + обязывает `ORCH_PROJECTS_JSON` на новом хосте. +- A10 (`watchdog/config.py` `metrics_url` 127.0.0.1:8500) — уже env-driven; при смене прод-порта + оператор задаёт `WATCHDOG_METRICS_URL` (строка чек-листа о когерентности портов: + `ORCH_DEPLOY_PROD_TARGET_PORT` ⇄ `WATCHDOG_METRICS_URL` ⇄ `ORCH_POST_DEPLOY_BASE_URL`). +- `onboarding/` (ORCH-009) — не форкается; новые env-ключи отражаются в его `.env.example`-скелете + только при фактическом расхождении. + +## Альтернативы + +- **`ORCH_SELF_HOSTING_REPO` как конфиг-ключ** — отвергнуто: превращает опечатку оператора в + активацию деплой-машинерии на чужом репо или тихое выключение всех self-гейтов (D3); конвенция + бесплатна при stateless-тираже. +- **`_STAGING_PORT` оставить константой** — отвергнуто: реестр B6 (AC-6) требует параметризации + порта в compose `command:`; константа в `image_freshness` при конфигурируемом compose-порте даёт + рассинхрон (rebuild целится в 8501, staging слушает иное) — хуже управляемой пары + «ключ + fail-closed guard» (D4). +- **Тихий fallback guard'а на 8501 при misconfig** — отвергнуто: молчаливая подмена таргета — + ровно тот класс отказа, против которого ORCH-058 строился; отказ громче и честнее. +- **Shell-form CMD / `ENV PORT` в Dockerfile** — отвергнуто: меняет PID-1/сигнальную семантику + выверенной пары `init: true` + exec-form (B-2) ради порта, который уже параметризуем на слое + compose (D5). +- **Генератор секретов как режим `onboard_project.py`** — отвергнуто: разные жизненные циклы + (онбординг проекта на живой платформе vs provisioning хоста), связывание независимых + операторских сценариев (D8). +- **Отдельный smoke-скрипт-обвязка** — отвергнуто (сейчас): каждый шаг runbook уже машинно + проверяем существующими кирпичами; скрипт = новая поверхность сопровождения без новой гарантии. + Дверь открыта: Lite/Bundled-задачи могут ввести обвязку поверх того же runbook (D9). +- **Allowlist-записи для `config.py` вместо структурного исключения** — отвергнуто: allowlist + обязан быть пуст (AC-1/AC-7); вечные записи о легитимных дефолтах девальвируют его сигнал (D10). + +## Последствия + +- **+** Платформа разворачивается на новой инфре только env/конфигом: четыре код-блокера закрыты + тремя ключами + реюзом существующих; инфра-файлы интерполируются; секреты выпускаются заново; + smoke даёт явный PASS/FAIL. Критический путь эпика ORCH-10 разблокирован. +- **+** Инвариант ORCH-058 усилен: анти-prod-гарантия freshness-пути теперь исполняемый guard, + а не подразумеваемая константа. +- **+** Возврат хардкода ломает CI структурно (сканер), а не ловится ревью. +- **−** Поверхность конфигурации растёт (~13 новых env-имён). Митигейшн: дефолты = боевым + значениям (ничего настраивать на текущем хосте не нужно), карта env в INFRA.md/REPLICATION.md, + TC-06/TC-08 сверяют полноту и резолв. +- **−** Правка двух safety-critical билдеров команд (D7) и compose-файла прод-сервиса (D5). + Митигейшн: изменения чисто аддитивные (одно env-присваивание; `command:` = текущему CMD), + exit-контракт хука не тронут, полный регресс + staging-гейт 8501 перед прод-деплоем (NFR-1). +- **−** Compose-интерполяция читает `.env`/shell, а не `env_file` — возможна операторская путаница + на staging. Митигейшн: правило явно зафиксировано (D1) и попадает в REPLICATION.md. +- **Откат:** не задавать новые переменные (дефолты = прежнее поведение — kill-switch-природа, + NFR-2); полный откат — revert PR (изменение конфигурационное, без миграций состояния). + +## Ссылки + +- BRD: `docs/work-items/ORCH-101/01-brd.md` +- TRZ: `docs/work-items/ORCH-101/02-trz.md` (нормативный реестр §3.1, вопросы §3.4 А-1…А-5) +- Acceptance: `docs/work-items/ORCH-101/03-acceptance-criteria.md` (AC-1…AC-8) +- Test plan: `docs/work-items/ORCH-101/04-test-plan.yaml` (TC-01…TC-12) +- Сквозной ADR: `docs/architecture/adr/adr-0036-replication-foundation-host-parametrization.md` +- Инварианты соседей: `docs/architecture/adr/adr-0005-container-runs-as-host-uid.md` (ORCH-040), + `adr-0008-staging-image-provenance.md` (ORCH-058), `adr-0007-executable-self-deploy.md` (ORCH-036), + `adr-0035-turnkey-project-onboarding.md` (ORCH-009) +- Сверено по коду: `src/plane_sync.py:1064`, `src/agents/launcher.py:592–599,823–831`, + `src/self_deploy.py:330–337`, `src/post_deploy.py:573–580`, `src/image_freshness.py:60–62,263–280`, + `src/qg/checks.py:517`, `src/fs_normalize.py:529–540`, `src/config.py:33–49,193–209`, + `docker-compose.yml`, `Dockerfile`, `scripts/orchestrator-deploy-hook.sh:38` diff --git a/docs/work-items/ORCH-101/07-infra-requirements.md b/docs/work-items/ORCH-101/07-infra-requirements.md new file mode 100644 index 0000000..a0c857f --- /dev/null +++ b/docs/work-items/ORCH-101/07-infra-requirements.md @@ -0,0 +1,80 @@ +--- +work_item: ORCH-101 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-10 +model_used: claude-opus-4-8 +--- + +# 07 — Инфра-требования: ORCH-101 — ORCH-10-common: расхардкод + секреты + smoke + +Work Item: **ORCH-101** · Repo: **orchestrator** · Стадия: architecture + +> Топология НЕ меняется (контейнеры/порты/сеть/тома — те же при дефолтах); меняется +> **параметризуемость** инфра-файлов. Раздел фиксирует карту переменных и правила раската. + +## I-1. Топология / окружения + +- **Без изменений при дефолтах:** те же 3 сервиса (`orchestrator` 8500, `orchestrator-watchdog`, + `orchestrator-staging` 8501 под профилем `staging`), `network_mode: host`, те же тома и + `group_add` docker-gid («МИНА 1» ORCH-040 — сохраняется, литерал → `${ORCH_DOCKER_GID:-999}`). +- `docker-compose.yml` переводится на интерполяцию `${VAR:-default}` (реестр ТЗ §3.1 B; карта — + ADR-001 D6); `Dockerfile` получает `ARG APP_UID/APP_GID/APP_USER/APP_HOME` (D5); оба сервиса + получают явный `command:` с портом из env (`${ORCH_DEPLOY_PROD_TARGET_PORT:-8500}` / + `${ORCH_STAGING_PORT:-8501}`) — дефолтный резолв эквивалентен текущей конфигурации (AC-2/TC-06). +- **Источник интерполяции** — `.env` проекта / shell-окружение (НЕ `env_file` сервиса): + интерполяционные значения тиража живут в `.env` (ADR-001 D1; попадает в REPLICATION.md). +- Имена сервисов/контейнеров/образов, профиль `staging`, `network_mode: host`, контейнерные пути + (`/app/data`, `/repos`, `/opt/claude-code`) — платформенные константы (ADR-001 D3/D4/D6). + +## I-2. Переменные окружения / секреты + +**Новые `Settings`-ключи** (дефолт = боевому значению; см. ADR-001 D2/D4): + +| env | Дефолт | Назначение | +|---|---|---| +| `ORCH_AGENT_HOME_DIR` | `/home/slin` | HOME акторских процессов (launcher ×2 / self-deploy / post-deploy) + таргеты маунтов + `APP_HOME` | +| `ORCH_AGENT_GIT_NAME` | `claude-bot` | git-имя агентских коммитов | +| `ORCH_GIT_EMAIL_DOMAIN` | `mva154.local` | домен git-email всех акторов (`@`) | +| `ORCH_STAGING_PORT` | `8501` | порт staging: `image_freshness` (c guard'ом ≠ прод-порт) + compose `command:` | + +**Новые compose-only переменные:** `ORCH_HOST_CLAUDE_DIR`, `ORCH_HOST_CLAUDE_JSON`, +`ORCH_HOST_SSH_DIR`, `ORCH_HOST_CLAUDE_CODE_DIR`, `ORCH_HOST_NODE_BIN`, `ORCH_DOCKER_GID`, +`ORCH_RUN_UID`, `ORCH_RUN_GID` (дефолты — текущие значения; полная карта — ADR-001 D6). +**Реюз существующих имён:** `ORCH_HOST_REPOS_DIR`, `ORCH_DEPLOY_SSH_USER`, +`ORCH_DEPLOY_HOST_REPO_PATH`, `ORCH_DEPLOY_PROD_TARGET_PORT`, legacy `DEPLOY_HOOK_SCRIPT`. +**Deploy-hook:** `REPO="${REPO:-/home/slin/repos/orchestrator}"` + явная передача `REPO=` обоими +инвокерами (ADR-001 D7). + +**Секреты (BR-3 / AC-5):** новый stdlib-скрипт `scripts/gen_secrets.py` — криптослучайные +`ORCH_PLANE_WEBHOOK_SECRET`/`ORCH_GITEA_WEBHOOK_SECRET` (`secrets.token_hex(32)`), печать по +умолчанию, `--write` с отказом при существующем `.env` (перезапись только `--force`). Внешние +токены (`ORCH_PLANE_API_TOKEN`, `ORCH_PLANE_BOT_*`, `ORCH_GITEA_TOKEN`, `ORCH_TELEGRAM_BOT_TOKEN`, +`WATCHDOG_TG_*`) — по чек-листу REPLICATION.md (где выпустить → куда вписать → как проверить). +Боевые секреты текущего хоста не покидают его (NFR-3); в гит — только шаблоны/плейсхолдеры +(правило агентов №8); `.env.example` доводится до 100% обязательных ключей, `.env.staging.example` +согласуется. + +**Карта env в `docs/operations/INFRA.md`** дополняется всеми новыми ключами; deployment-раздел — +новый `docs/operations/REPLICATION.md` (FR-7). Чек-лист тиража обязывает: `ORCH_PROJECTS_JSON` +(fallback-реестр UUID'ов чужого Plane не сматчится), когерентность портов +`ORCH_DEPLOY_PROD_TARGET_PORT` ⇄ `WATCHDOG_METRICS_URL` ⇄ `ORCH_POST_DEPLOY_BASE_URL`. + +## I-3. Деплой / рестарт + +- **Рестарт прод-контейнера в рамках задачи — НЕ требуется и запрещён** (NFR-1, self-hosting): + правки `docker-compose.yml`/`Dockerfile`/хука инертны до следующего штатного деплоя через + конвейер (staging 8501 → ручной `Confirm Deploy`, ORCH-059). +- На текущем хосте ничего донастраивать не нужно: все дефолты = боевым значениям; пустой/ + неизменённый `.env` → поведение 1:1 (BR-5). Откат = не задавать переменные (NFR-2). +- Инвариант ORCH-058 сохранён и усилен: freshness-путь fail-closed отказывает при + `ORCH_STAGING_PORT == прод-порт` (ADR-001 D4); INV-4 не затрагивается. + +## I-4. CI/CD + +- `.gitea/workflows/` — **без изменений**. Новые тесты (`test_no_host_hardcodes.py`, + `test_host_config_keys.py`, `test_infra_parametrization.py`, `test_secrets_gen.py`, + `test_replication_smoke.py`) попадают в существующие гейты (`check_ci_green`/ + `check_tests_passed`/merge-gate re-test) автоматически — новых QG не вводится (NFR-6). +- Новых pip/системных зависимостей нет (генератор секретов — stdlib). diff --git a/docs/work-items/ORCH-101/08-data-requirements.md b/docs/work-items/ORCH-101/08-data-requirements.md new file mode 100644 index 0000000..ce35bee --- /dev/null +++ b/docs/work-items/ORCH-101/08-data-requirements.md @@ -0,0 +1,32 @@ +--- +work_item: ORCH-101 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-10 +model_used: claude-opus-4-8 +--- + +# 08 — Требования к данным: ORCH-101 — ORCH-10-common: расхардкод + секреты + smoke + +Work Item: **ORCH-101** · Repo: **orchestrator** · Стадия: architecture + +> When-applicable / информационный. Задача конфигурационная — данные и схема БД не затрагиваются; +> файл создан для аудитопригодности с явными `N/A`. + +## Изменения схемы БД + +`N/A` — таблицы/индексы/миграции не добавляются и не меняются; `init_db()` не трогается (NFR-6, +ТЗ §5). Тираж stateless (решение Славы 10.06): перенос данных/БД с боевого хоста не предполагается +ни одним шагом (smoke-процедура это явно проверяет — AC-3). + +## Новые/изменённые сущности + +Нет. Новые конфиг-ключи (`agent_home_dir`, `agent_git_name`, `git_email_domain`, `staging_port`) — +слой `Settings` (env), не данные. + +## Совместимость данных / миграции + +`N/A` — общая прод-БД (self-hosting, enduro-trails) не затрагивается; `ORCH_DB_PATH` и layout +`/app/data` остаются прежними (контейнерные пути — платформенная конвенция, ADR-001 D6). На новом +хосте БД создаётся с нуля штатным `init_db()`. diff --git a/docs/work-items/ORCH-101/10-tech-risks.md b/docs/work-items/ORCH-101/10-tech-risks.md new file mode 100644 index 0000000..f38fef5 --- /dev/null +++ b/docs/work-items/ORCH-101/10-tech-risks.md @@ -0,0 +1,38 @@ +--- +work_item: ORCH-101 +stage: architecture +author_agent: architect +status: proposed +created_at: 2026-06-10 +model_used: claude-opus-4-8 +--- + +# 10 — Технические риски: ORCH-101 — ORCH-10-common: расхардкод + секреты + smoke + +Work Item: **ORCH-101** · Repo: **orchestrator** · Стадия: architecture + +> Информационный (гейтом не парсится). Детализация рисков Р-1…Р-5 BRD §8 в привязке к решениям +> ADR-001 (D1…D10). + +## Реестр рисков + +| ID | Риск | Вер. | Влия. | Митигейшн | +|----|------|------|-------|-----------| +| TR-1 | **Регресс горячих путей при параметризации env-словарей акторов** (launcher ×2 / self-deploy / post-deploy): опечатка в ключе/дефолте ломает git-коммиты или credentials-резолв claude CLI (HOME) у ВСЕХ проектов общего инстанса (Р-1 BRD) | Низ. | Выс. | Дефолты байт-в-байт = боевым (`/home/slin`, `claude-bot@mva154.local` — BR-5); TC-04/TC-05 фиксируют итоговые словари при дефолтах И при переопределении; полный регресс TC-12; staging-гейт 8501 перед прод-выкатом (NFR-1) | +| TR-2 | **Ослабление инварианта ORCH-058 при конфигуризации staging-порта** (`ORCH_STAGING_PORT=8500` нацеливает rebuild/recreate на прод; Р-2 BRD) | Низ. | Выс. | Fail-closed guard ДО любого ssh/build: `staging_port == deploy_prod_target_port` → отказ + алерт, без тихого fallback (ADR-001 D4); explicit-pass `TARGET_PORT=` хуку сохранён; TC-11 проверяет guard | +| TR-3 | **Флап анти-регресс сканера** (ложные срабатывания на комментарии/докстринги или вечно-непустой allowlist из-за дефолтов config.py; Р-3 BRD) | Сред. | Низ. | `tokenize`-исключение комментариев/докстрингов (не regex); структурное исключение `src/config.py`+`watchdog/config.py` как канонических мест дефолтов (BR-1); негативная самопроверка TC-02; список литералов централизован (ADR-001 D10) | +| TR-4 | **Неполный аудит**: пропущенный хардкод всплывает на первом реальном тираже (Р-4 BRD) | Сред. | Сред. | Реестр §3.1 нормативен и перепроверен на стадии architecture повторным grep'ом (код-блокеры = ровно A1–A4, см. ADR-001 «Контекст»); сканер CI держит классы литералов навсегда; smoke-процедура (D9) — последняя линия обнаружения на целевой инфре | +| TR-5 | **Правка safety-critical билдеров команд деплоя** (D7: `build_deploy_command` / `image_freshness` env-prefix; D5: `command:` прод-сервиса compose) — ошибка ломает self-deploy/rollback | Низ. | Выс. | Изменения строго аддитивные: одно env-присваивание `REPO=` (exit-контракт хука 0/1/2 не тронут, ORCH-036 прочитан); `command:` прод = байт-в-байт текущему CMD при дефолтах (TC-06); существующие self-deploy/freshness тесты + staging-прогон | +| TR-6 | **Путаница источников env**: compose-интерполяция читает `.env`/shell, а не `env_file` (`.env.staging` НЕ влияет на `${VAR}`) → оператор тиража задаёт переменную «не туда» | Сред. | Низ. | Правило явно зафиксировано (ADR-001 D1) и входит в REPLICATION.md; дефолты делают ошибку безопасной (резолв в боевые значения, не в мусор); TC-06 проверяет дефолт-резолв | +| TR-7 | **Рассинхрон группы ORCH-040** (uid/gid/HOME/маунты/`useradd`) при частичном переопределении (например, сменили `ORCH_AGENT_HOME_DIR`, забыли пересобрать образ с `APP_HOME`) | Низ. | Сред. | Группа управляется одними env-именами насквозь (compose `build.args` ← те же `ORCH_RUN_UID/GID`/`ORCH_AGENT_HOME_DIR`, ADR-001 D5/D6); «МИНА 1» `group_add` сохранена; согласованная группа описана в REPLICATION.md как «менять вместе»; TC-06/TC-07 | +| TR-8 | **Слабые/затёртые секреты**: детерминированная генерация или молчаливая перезапись `.env` уничтожает работающий комплект | Низ. | Выс. | `secrets.token_hex(32)` (криптослучайно, 32 байта); отказ при существующем файле, перезапись только явным `--force` (NFR-3, ADR-001 D8); TC-09 проверяет различие повторных запусков и отказ | + +## Сводный вывод + +Доминирующий класс — **регресс общего прод-инстанса через горячие пути** (TR-1/TR-2/TR-5): +вероятность низкая (kill-switch-природа дефолтов: на текущем хосте без новых env поведение 1:1), +влияние высокое (self-hosting, общая БД с enduro-trails) → ключевая страховка — полный регресс + +обязательный staging-гейт 8501 + ручной `Confirm Deploy` (прод-контейнер в рамках задачи не +рестартуется, NFR-1). Эскалация `arch:major-change` **не требуется**: ни новой стадии, ни нового +компонента, ни смены БД — конвейер и QG байт-в-байт (NFR-6); возврат в анализ не нужен (ТЗ +выполнимо без нарушения принципов). Остаточный риск для прод-конвейера — **низкий**.