orchestrator/docs/work-items/ORCH-112/02-trz.md

work_item, stage, author_agent, status, created_at, model_used

work_item	stage	author_agent	status	created_at	model_used
ORCH-112	analysis	analyst	ready-for-review	2026-06-15	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/ перед изменением, инварианты не ломать.