orchestrator/docs/work-items/ORCH-112/07-infra-requirements.md

work_item, stage, author_agent, status, created_at, model_used

work_item	stage	author_agent	status	created_at	model_used
ORCH-112	architecture	architect	proposed	2026-06-15	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).