--- work_item: ORCH-112 stage: analysis author_agent: analyst status: ready-for-review created_at: 2026-06-15 model_used: claude-opus-4-8 --- # 02 — ТЗ (TRZ): ORCH-112 — failed/cancelled task artifacts must be cleaned from shared checkout Work Item: **ORCH-112** · Repo: **orchestrator** · Стадия: analysis > ТЗ описывает **требования и ограничения к реализации**, выведенные из BRD и фактического кода. > Архитектурное **решение** (какой механизм гигиены/изоляции выбрать) — задача архитектора (`06-adr/`), > т.к. задача эскалирована в full-cycle (`01-brd.md` → `escalate: full-cycle`). ## 1. Сводка изменения Сделать self-deploy устойчивым к **грязной shared deploy-базе** и гарантировать сходимость базы к чистому `origin/main` после failed/cancelled/брошенных задач. Корень симптома — голый `git pull origin main` в `scripts/orchestrator-deploy-hook.sh` (строка 226), исполняемый в `$REPO` (= `settings.deploy_host_repo_path` = main clone), который падает при любой локальной правке tracked-файла. Требуется: (а) приведение deploy-базы к чистому `origin/main` перед/в момент pull **без ручного вмешательства**, со строгим сохранением deploy-rollback-состояния; (б) документирование + (по возможности) энфорс инварианта «main checkout — deploy-база, не workspace»; (в) наблюдаемость. ## 2. Задействованные модули / пути | Путь | Действие | Примечание | |------|----------|-----------| | `scripts/orchestrator-deploy-hook.sh` | изменить | строки 224-226: голый `git pull origin main` в `$REPO` — точка отказа (FR-1) | | `src/self_deploy.py` | возможно изменить | `build_deploy_command` / `initiate_deploy` / `rebuild_staging_image` строят инвокацию хука — возможная точка передачи гигиены/флага (решает архитектор) | | `src/stage_engine.py` | возможно изменить | `cancel_task` (шаг 3d, ~2330-2343) — каскад cancel; расширение гигиены на shared-базу (FR-2, если выбран этот путь) | | `src/git_worktree.py` | возможно изменить | модель main clone ↔ worktree; возможный helper приведения базы к чистоте / верификация инварианта (BR-3) | | `src/config.py` | изменить | новый kill-switch + флаги области (FR-5) | | `src/.py` (напр. `checkout_hygiene.py`) | возможно создать | чистый never-raise leaf политики гигиены (по образцу `serial_gate`/`cancel`) — **создавать ли** решает архитектор | | `docs/operations/INFRA.md` | изменить | инвариант «shared checkout — deploy-база, не workspace» (BR-3) | | `docs/architecture/README.md` | изменить | описать политику гигиены/жизненного цикла deploy-базы | | `CHANGELOG.md`, `CLAUDE.md` | изменить | правило «docs = golden source» (CLAUDE.md §2) | | `tests/test_<...>.py` | создать | регресс + покрытие (см. `04-test-plan.yaml`) | ## 3. Функциональные требования ### FR-1 — Устойчивый self-deploy `git pull` (BR-1, BR-5) - На пути self-deploy (`scripts/orchestrator-deploy-hook.sh`, шаг «2. Pull latest code») `git pull origin main` **не должен падать** из-за грязного рабочего дерева `$REPO`. - Перед обновлением база приводится к чистому, актуальному `origin/main` (приведение tracked- и untracked-изменений к состоянию `origin/main`), **с сохранением** артефактов из NFR-2. - На **уже чистой** базе результат — обычный fast-forward; наблюдаемое поведение и exit-коды (0/1/2, ORCH-036) — **байт-в-байт прежние** (BR-5). - Контракт: never-break — сбой шага гигиены не должен ухудшать исход относительно текущего голого pull (fail-safe). ### FR-2 — Сходимость shared-базы после failed/cancelled/брошенной задачи (BR-2) - После терминации задачи (`failed` job-исход / `cancelled` через STOP / брошенный WIP) в shared checkout **не остаётся** рабочих остатков, способных заблокировать будущий деплой/git-операцию. - Допустимая трактовка «сходимости» (на выбор архитектора, **не** прескриптивно здесь): автоочистка непосредственно в self-deploy перед pull (FR-1) **и/или** активный «дворник», приводящий `/` к чистому `origin/main`. - Каскад `cancel_task` (ORCH-090) уже чистит **worktree + remote-ветку**; расширение на shared-базу (если выбрано) делается тем же never-raise best-effort способом. ### FR-3 — Инвариант deploy-базы (BR-3) - Задокументировать: `/` — deploy/worktree-management база; рабочие изменения туда **не пишутся** конвейером/агентами (агенты — worktree `git_worktree`; build — worktree-контекст; fallback'и гейтов — read-only `git show origin/main`). - Верифицировать, что текущий код этот инвариант соблюдает (анализ ORCH-112: соблюдает; единственные обращения к main clone — read-only/fetch/worktree-управление). Где осуществимо — добавить лёгкий guard/проверку (решает архитектор), **без** изменения горячих путей. ### FR-4 — Наблюдаемость (BR-4) - Обнаружение грязной deploy-базы и факт автоочистки (число/имена сброшенных путей) или **отказ** гигиены — лог (структурная запись) + Telegram-алерт (`send_telegram`, кликабельный номер задачи, best-effort, never-raise). Опционально — read-only снапшот в `GET /queue` (решает архитектор). ### FR-5 — Условность / kill-switch (BR-5, NFR-3, NFR-6) - Новое поведение под **kill-switch** (env `ORCH_*`, по образцу `serial_gate_enabled`/`stop_status_enabled`); выключенный флаг → деплой байт-в-байт прежний (голый `git pull origin main`). - Область — self-hosting (`orchestrator`); прочие репо/синхронный деплой агентом — не ухудшаются. - `applies(repo)` (локальный, без сети) проверяется первым. ## 4. Изменения API **Нет** обязательных. Опционально (на усмотрение архитектора) — read-only блок (напр. `checkout_hygiene`) в существующем `GET /queue` для наблюдаемости. Новых управляющих эндпоинтов не требуется. ## 5. Изменения схемы БД **Нет.** Состояние гигиены, если нужно, — in-memory / sentinel-файлы (паттерн `self_deploy`/`merge_gate`), без миграции БД. Аддитивная таблица не требуется. ## 6. Требования к новым/изменённым QG checks **Нет.** Это **не** Quality Gate и не стадия — это устойчивость deploy-пути и политика гигиены. `STAGE_TRANSITIONS` / реестр `QG_CHECKS` / семантика и имена `check_*` / machine-verdict ключи (`deploy_status:`/`staging_status:`/…) — **байт-в-байт не тронуты** (NFR-5). ## 7. Совместимость / регресс - **Обратная совместимость:** kill-switch off → голый `git pull origin main` (1:1 до ORCH-112); чистая база → fast-forward без изменений (BR-5). - **Область раската:** self-hosting `orchestrator`; enduro/прочие — нулевая регрессия. - **Обратимость:** выключение флага мгновенно возвращает прежнее поведение. - **Сохранность (жёсткое ограничение, NFR-2):** гигиена **не удаляет** `$REPO/.deploy-prev-image-*` (rollback), `deploy-hook.log`, sibling `/.deploy-state-*` / `.merge-lease-*.json`, админ-записи `.git/worktrees`. Любой `clean`-скоуп обязан их исключать. - **Self-hosting инварианты (NFR-1):** никогда не трогать `main` на remote, не force-push, не рестартить прод вне гейта, не сносить worktree/ветки других активных задач, оперировать только настроенным путём deploy-базы. Exit-code-контракт хука (0/1/2) сохранён. - **Артефакты pipeline:** создаются/обновляются обычные docs work item (`01..04` этой задачи, `06-adr/` на стадии architecture после эскалации, `14-deploy-log.md` при деплое). Новых pipeline-артефактов задача не вводит. - **Трассировка (CLAUDE.md §9 / ORCH-078):** правки маркированных блоков (ORCH-036 self-deploy, ORCH-058 image-freshness, ORCH-090 cancel) — сверять с их `06-adr/` перед изменением, инварианты не ломать.