---
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/<new_leaf>.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) **и/или** активный «дворник», приводящий
  `<host_repos_dir>/<repo>` к чистому `origin/main`.
- Каскад `cancel_task` (ORCH-090) уже чистит **worktree + remote-ветку**; расширение на shared-базу
  (если выбрано) делается тем же never-raise best-effort способом.

### FR-3 — Инвариант deploy-базы (BR-3)
- Задокументировать: `<host_repos_dir>/<repo>` — 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 `<repos_dir>/.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/` перед изменением, инварианты
  не ломать.
