---
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:<port>/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/<branch> docs/work-items/<id>/`) |
| 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`
