111 lines
10 KiB
Markdown
111 lines
10 KiB
Markdown
---
|
||
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/` перед изменением, инварианты
|
||
не ломать.
|