---
work_item: ORCH-112
stage: architecture
author_agent: architect
status: proposed
created_at: 2026-06-15
model_used: claude-opus-4-8
---

# 07 — Инфра-требования: ORCH-112 — гигиена shared deploy-базы

Work Item: **ORCH-112** · Repo: **orchestrator** · Стадия: architecture

> When-applicable. Затрагивается **жизненный цикл shared deploy-базы** (`<host_repos_dir>/<repo>`),
> а не топология контейнеров/портов/томов. Контейнеры/сеть/тома — `N/A`.

## I-1. Топология / окружения
**Без изменений в составе.** Контейнеры (`orchestrator` 8500 / `orchestrator-staging` 8501), сеть
(`network_mode: host`), порты, тома — прежние.

Затрагивается **deploy-база** `<host_repos_dir>/<repo>` (= `/home/slin/repos/orchestrator` ==
`/repos/orchestrator` в контейнере через bind-mount == `settings.deploy_host_repo_path`). **Нормативно
закрепляется инвариант:** deploy-база — **deploy/worktree-management база, НЕ редактируемый workspace**.
Рабочие изменения туда не пишутся конвейером/агентами (агенты — worktree `/repos/_wt/<repo>/<branch>`,
build — worktree-контекст, fallback'и гейтов — read-only `git show origin/main`). Документируется в
`docs/operations/INFRA.md` (топология + self-hosting) и `docs/architecture/README.md` (раздел ORCH-36).

**Контракт сохранности рабочего дерева deploy-базы (NFR-2, жёсткий):** автоочистка hygiene
(`git clean -fd`, **без** `-x`) **обязана сохранять**:
| Артефакт | Расположение | Почему сохраняется |
|----------|--------------|--------------------|
| `.deploy-prev-image-prod` / `.deploy-prev-image-staging` | `$REPO/` (untracked, НЕ ignored) | rollback-снимок → `-e '.deploy-prev-image-*'` |
| `deploy-hook.log` | `$REPO/` (fallback-лог) | аудит → `-e 'deploy-hook.log'` |
| `.env`, `data/`, `*.db`, `build/` | `$REPO/` (gitignored) | прод-секреты/БД → переживают `git clean` **без** `-x` |
| `.deploy-state-<repo>/*`, `.merge-lease-<repo>.json` | `<repos_dir>/` (sibling, родитель `$REPO`) | вне области `git clean` в `$REPO` |
| `.git/worktrees/*` | `$REPO/.git/` | `git clean` никогда не трогает `.git/` |

## I-2. Переменные окружения / секреты
Две новые env-переменные (`src/config.py`, дефолт = боевое; **обновить `.env.example`**):
| Ключ | Env | Дефолт | Назначение |
|------|-----|--------|-----------|
| `checkout_hygiene_enabled` | `ORCH_CHECKOUT_HYGIENE_ENABLED` | `True` | kill-switch resilient-pull; `False` → голый `git pull` (1:1 до ORCH-112) |
| `checkout_hygiene_repos` | `ORCH_CHECKOUT_HYGIENE_REPOS` | `""` | CSV-скоуп; пусто → self-hosting only (`orchestrator`) |

Внутренние env, инжектируемые в detached-хук `self_deploy.build_deploy_command` (не операторские):
`CHECKOUT_HYGIENE=1`, `HYGIENE_REPORT=<host_state_dir>/hygiene`. Новых секретов нет.

## I-3. Деплой / рестарт
**Рестарт прод-контейнера задачей ORCH-112 — НЕ требуется и ЗАПРЕЩЁН** (self-hosting инвариант,
CLAUDE.md). Изменение активируется штатно: новый промпт/хук/код `cat`-ается/деплоится в обычном
self-deploy-цикле через **staging-гейт (8501)** сначала, затем `Confirm Deploy` (ORCH-059). Хук-блок
hygiene исполняется **только** в `--deploy` режиме (где есть `git pull`); `--build-staging` собирает из
worktree и не пуллит → не затронут. Exit-code-контракт хука (0/1/2, ORCH-036) — байт-в-байт.

## I-4. CI/CD
**Без изменений** `.gitea/workflows/`. Новый тест-модуль `tests/test_deploy_checkout_hygiene.py`
(шелл-симуляция хука во временном git-репо, без сети/прода/ssh — образец
`tests/test_deploy_hook_rollback_sim.py`) исполняется обычным `pytest tests/ -q`. Полный регресс обязан
оставаться зелёным (NFR-5).
