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

02 — Техническое задание (ТЗ)

Work Item: ORCH-043 Тема: merge-gate + auto-rebase + re-test (безопасная параллель в одном репо) Автор: Analyst

ТЗ описывает ТРЕБУЕМОЕ поведение и конкретные точки изменения кода. Окончательный выбор места встройки в конвейер (новая стадия vs гейт существующего перехода vs шаг перед слиянием) и детали reconciliation — за архитектором (ADR в 06-adr/). Если ТЗ окажется нереализуемым — вернуть на стадию analysis, не комментировать задним числом.

---

1. Задействованные модули src/

Модуль	Роль в изменении
src/merge_gate.py (новый)	Ядро фичи: ancestor-check, auto-rebase, re-test, merge-lock. Чистые функции + git-операции в worktree.
src/qg/checks.py	Новый QG-check check_branch_mergeable (merge-gate) + регистрация в QG_CHECKS. Переиспользует паттерн check_tests_local (pytest в worktree) и _repo_path.
src/stages.py	Встройка merge-gate в STAGE_TRANSITIONS (точное место — за архитектором; см. §6).
src/stage_engine.py	Ветка отката merge-gate → development в _handle_qg_failure_rollbacks + диспетчеризация нового check в _run_qg.
src/git_worktree.py	Возможные хелперы: проверка «behind origin/main», rebase, push --force-with-lease. Не ломать сигнатуры ensure_worktree / get_worktree_path.
src/config.py	Новые settings: тайм-аут re-test, вкл/выкл гейта, политика отстающей ветки, тайм-аут lock.
src/agents/launcher.py	Если merge-gate встраивается как шаг перед слиянием на стадии deploy — точка, где deployer запускается, может потребовать координации с lock (за архитектором).
tests/	Новые тесты (см. 04-test-plan.yaml) + обновление snapshot-тестов реестра/стадий.

2. Функциональные требования к src/merge_gate.py

Предлагаемый публичный контракт (имена финализирует архитектор; поведение обязательно):

2.1 branch_is_behind_main(repo, branch) -> bool

• git fetch origin main в main-clone/worktree (best-effort, never-raise → трактуем как «не удалось определить» и НЕ пропускаем слияние вслепую).
• Ветка считается отстающей, если origin/main не является предком HEAD ветки (git merge-base --is-ancestor origin/main <branch> → ненулевой код).

2.2 auto_rebase_onto_main(repo, branch) -> (ok: bool, reason: str)

• Выполняется в изолированном worktree ветки (ensure_worktree), НЕ в общем clone.
• Догнать ветку до origin/main (rebase либо merge — выбор архитектора; критично: результат содержит весь origin/main и историю/изменения ветки).
• Текстовый конфликт → отменить операцию (git rebase --abort / git merge --abort), worktree оставить чистым, вернуть (False, "rebase conflict: <файлы>").
• Чистый догон → git push --force-with-lease origin <branch> (ТОЛЬКО ветка задачи, НИКОГДА main). Вернуть (True, ...).
• Контракт never-raise: любая git/OS-ошибка → (False, "<reason>"), не исключение.

2.3 retest_branch(repo, branch) -> (ok: bool, reason: str)

• Прогнать тест-набор проекта в worktree догнанной ветки. Канон — как в check_tests_local: python -m pytest (точная команда/каталог — за архитектором, согласованно с CI-конфигом .gitea/workflows/).
• Тайм-аут settings.merge_retest_timeout_s; превышение → (False, "re-test timeout").
• Возврат: (True, "re-test green") при коде 0, иначе (False, "re-test failed: <tail>").

2.4 Merge-lock (сериализация, BR-5)

• Реализовать межзадачную сериализацию «догон+re-test+слияние» в пределах одного repo.
• Допустимые реализации (выбор архитектора): файловый lock в repos_dir, advisory-lock, либо строка-замок в SQLite. Требования: restart-safe, с тайм-аутом settings.merge_lock_timeout_s, корректное освобождение при ошибке/падении.
• Под локом: повторно сверить «не отстаёт» ПОСЛЕ захвата (double-check), т.к. main мог уйти, пока ждали lock.

3. Новый QG-check (src/qg/checks.py)

check_branch_mergeable(repo, work_item_id, branch) -> tuple[bool, str]

Поведение (детерминированно, без участия LLM):

1. Захватить merge-lock для repo (с тайм-аутом). Не удалось → (False, "merge-lock busy").
2. Если ветка не отстаёт от origin/main → (True, "branch up-to-date with main").
3. Иначе auto_rebase_onto_main:
   • конфликт → (False, "rebase conflict: ...");
   • успех → retest_branch:
     • зелёный → (True, "rebased onto main, re-test green");
     • красный/тайм-аут → (False, "re-test failed after rebase: ...").
4. Освободить lock в finally.

• Зарегистрировать в QG_CHECKS под ключом "check_branch_mergeable".
• Контракт never-raise (как у соседних чеков): исключение → (False, "<reason>").

Опционально (за архитектором): флаг settings.merge_gate_enabled; при False чек возвращает (True, "merge-gate disabled") (безопасный no-op для постепенного раскатывания, по образцу условного staging-гейта ORCH-35).

4. Изменения схемы БД

• Не требуется для базовой реализации (lock через файл/advisory).
• ЕСЛИ архитектор выберет lock через SQLite — добавить таблицу/строку-замок миграцией, совместимой с текущей инициализацией src/db.py (никаких ломающих изменений tasks, agent_runs, jobs, events). Это решение фиксируется в ADR.

5. Изменения API

• Новых HTTP-эндпоинтов не требуется.
• Допустимо (не обязательно) расширить GET /status или GET /queue индикатором «merge-gate: rebasing/re-testing/locked» для наблюдаемости — на усмотрение архитектора, без изменения существующих контрактов ответов.

6. Точки встройки в конвейер (требование + кандидаты)

Требование: merge-gate отрабатывает как можно ближе к фактическому слиянию в main и ДО него. Слияние ветки в main НЕ должно происходить в обход гейта.

Кандидаты (окончательно — ADR архитектора):

• (A) Гейт на переходе deploy-staging → deploy или новый под-гейт перед слиянием: deployer вливает PR на стадии deploy, поэтому проверка «догнать+re-test» логично встаёт непосредственно перед запуском deployer.
• (B) Новая стадия merge-gate между deploy-staging и deploy с агентом=None и qg="check_branch_mergeable".
• (C) Перенести само слияние в main из ответственности deployer-агента в детерминированный шаг оркестратора, защищённый merge-gate (более крупное изменение).

При любом варианте, меняющем STAGE_TRANSITIONS или QG_CHECKS:

• обновить docs/architecture/README.md (таблица стадий + реестр QG, §«Конвейер»);
• обновить snapshot-тесты tests/test_qg_registry_snapshot.py (_EXPECTED_QGS, _EXPECTED_TRANSITIONS) — осознанно, в этом же PR;
• сохранить порядок ключей STAGE_TRANSITIONS (от него зависит get_previous_stage).

7. Откаты (интеграция со stage_engine)

В _handle_qg_failure_rollbacks добавить ветку для merge-gate FAIL по образцу check_staging_status / check_deploy_status:

• update_task_stage(task_id, "development"), set_issue_blocked(work_item_id);
• комментарий в Plane (plane_add_comment, author="deployer" или системный) с причиной (конфликт rebase / красный re-test) — дословный reason гейта;
• Telegram-алерт (send_telegram);
• учитывать MAX_DEVELOPER_RETRIES, не плодить бесконечные заворот-циклы.
• В _run_qg добавить диспетчеризацию check_branch_mergeable с сигнатурой (repo, work_item_id, branch) (как у артефактных чеков).

8. Изменения конфигурации (src/config.py, env-префикс ORCH_)

Setting	Назначение	Дефолт (предложение)
merge_gate_enabled: bool	Глобальный вкл/выкл гейта	True
merge_retest_timeout_s: int	Тайм-аут повторного прогона тестов	600
merge_lock_timeout_s: int	Тайм-аут ожидания merge-lock	300
merge_gate_repos: str	(опц.) ограничить гейт списком репо; пусто = все	""

Значения и имена финализирует архитектор; задокументировать в .env.example и docs/architecture/README.md.

9. Требования к наблюдаемости / документации (golden source)

• Обновить docs/architecture/README.md: описание merge-gate, auto-rebase, re-test, merge-lock; при изменении стадий/реестра — соответствующие таблицы.
• Обновить CHANGELOG.md.
• Завести ADR docs/work-items/ORCH-043/06-adr/ADR-001-merge-gate.md (механизм догона, выбор rebase vs merge, реализация lock, место встройки).
• Все ветки кода — с лог-сообщениями (logger.info/warning/error) по образцу соседних гейтов, чтобы поведение читалось в /app/data/runs и логах сервиса.

10. Нефункциональные требования

• Безопасность self-hosting: никогда не push в main; force только --force-with-lease по ветке задачи; прод-контейнер orchestrator не рестартить/не ронять.
• Изоляция: все git-операции — в worktree ветки (ensure_worktree), не в общем clone, чтобы не словить S-4-гонку параллельных задач.
• Идемпотентность/restart-safe: lock и гейт корректно ведут себя при рестарте сервиса.
• Never-raise контракт у всех новых чеков/парсеров (как в текущем src/qg/checks.py).
• Совместимость: не менять сигнатуры/поведение существующих QG-чеков и вебхуков.

11. Артефакты pipeline, которые должны быть созданы/обновлены

• src/merge_gate.py (новый), изменения в src/qg/checks.py, src/stages.py, src/stage_engine.py, src/config.py, при необходимости src/git_worktree.py.
• Новые тесты в tests/ + обновлённые snapshot-тесты.
• docs/architecture/README.md, CHANGELOG.md, .env.example, docs/work-items/ORCH-043/06-adr/ADR-001-merge-gate.md.