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

ТЗ — ORCH-053: Sweeper потерянных webhook (реконсиляция застрявших стадий)

Work Item ID: ORCH-053 Базовая ветка: feature/ORCH-053-sweeper-webhook-stuck-task

Это ТЗ фиксирует конкретные изменения кода/конфига/доки. Архитектурные развилки (потокобезопасность, точная схема дампинга нотификаций, способ вызова async-обработчиков из sync-потока) фиксирует архитектор в 06-adr/. Если ТЗ окажется негодным — возврат в Анализ (не комментировать задним числом).

0. Живая разведка ПЕРЕД реализацией (обязательна)

Перед кодом разработчик обязан вживую проверить (как сейчас webhook продвигает стадию):

• src/webhooks/gitea.py::handle_ci_status (success-ветка ~стр.199–217) и handle_pr;
• src/webhooks/plane.py::handle_issue_updated / handle_status_start / handle_verdict / start_pipeline;
• src/stage_engine.py::advance_stage (унифицированный путь, finished_agent=None = webhook-путь);
• src/queue_worker.py (образец фонового daemon-потока + threading.Event + atomic claim);
• src/db.py::has_active_job_for_task / claim_next_job / update_task_stage (updated_at).

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

Модуль	Изменение
src/reconciler.py	НОВЫЙ. Фоновый sweeper/reconciler (класс + module-singleton, паттерн queue_worker). Обе ветки F-1 (gate-side) и F-2 (plane-side).
src/config.py	Новые настройки reconcile_* (интервал, kill-switch, per-stage grace, plane-poll flag).
src/main.py	Старт/стоп reconciler в lifespan (после worker.start() / перед worker.stop()).
src/stage_engine.py	Тонкий хелпер advance_if_gate_passed(...) (или reconcile_advance) — обёртка над advance_stage(..., finished_agent=None), подавляющая повторный спам нотификаций при провале гейта (продвижение — переиспользуется как есть).
src/plane_sync.py	НОВЫЙ хелпер list_issues_by_state(project_id, state_uuids) -> list[dict] (GET issues с пагинацией, фильтр по state). Используется F-2.
src/webhooks/gitea.py	F-3: усилить sha→branch резолв в handle_ci_status (fallback на БД-поиск task), логировать неразрезолв на уровне INFO (видимость).
src/webhooks/plane.py	F-2 переиспользует handle_issue_updated / handle_status_start / handle_verdict без дублирования логики (возможно, лёгкий рефактор для вызова из reconciler).
src/main.py (API)	F-4 (опц.): расширить /queue блоком reconcile-метрик или добавить GET /reconcile.

2. F-1 — Gate-side sweeper (реконсиляция по локальной БД)

Алгоритм одного прохода (reconcile_gate_once())

для каждой task где stage NOT IN ('done',) :
    если has_active_job_for_task(task.id):           continue   # в работе — не трогаем
    если get_qg_for_stage(task.stage) is None:       continue   # created/done — нет гейта
    grace = grace_for_stage(task.stage)
    если age(task.updated_at) < grace:               continue   # ещё не «застряла»
    # источник истины — гейт; путь продвижения — штатный
    advance_if_gate_passed(task.id, task.stage, task.repo, task.work_item_id, task.branch)

• Продвижение идёт через stage_engine.advance_stage(task_id, stage, repo, work_item_id, branch, finished_agent=None) — это тот же путь, которым пользуется Plane Approved-webhook (webhooks/plane._try_advance_stage). Никакой параллельной логики advance.
• Для development → advance_stage прогонит check_ci_green; passed → review + enqueue reviewer. Для review → check_reviewer_verdict (канонический гейт стадии из STAGE_TRANSITIONS, читает verdict: из 12-review.md). Для testing → check_tests_passed. Для deploy → check_deploy_status. Для deploy-staging → check_staging_status (+ merge-gate sub-gate отрабатывает внутри advance_stage как обычно).
• Стадия analysis (gQG check_analysis_approved): это человеческий гейт. В advance_stage при finished_agent=None он трактуется как approved-via-status и продвинет задачу — чего при потере именно Approved-webhka мы и хотим только если Plane реально в статусе Approved. Поэтому F-1 НЕ реконсилирует analysis (advance для analysis отдаётся F-2, которая сверяется с реальным статусом Plane). Архитектор фиксирует это решение в ADR (защита от ложного продвижения неодобренного BRD).

Подавление спама нотификаций (advance_if_gate_passed)

• Если гейт passed → advance_stage продвигает и шлёт штатные нотификации advance.
• Если гейт failed → НЕ повторять notify_qg_failure/plane_notify_qg на каждом тике. Хелпер вызывает advance_stage так, чтобы при провале была тишина (лог INFO/DEBUG), либо реализует продвижение, минуя ветку нотификации провала. Точную форму (флаг в advance_stage vs отдельный путь оценки гейта) выбирает архитектор; контракт: на застрявшей-но-красной задаче sweeper не спамит.

Защита от гонки

• has_active_job_for_task + update_task_stage обновляет updated_at → следующий тик увидит свежий updated_at и не сработает повторно.
• Если в момент тика прилетел живой webhook и поставил job — sweeper увидит активный job и пропустит задачу.
• max_concurrency=1: новый enqueued job встанет в общую очередь (без двойного запуска).

3. F-2 — Plane-side reconciler (опрос Plane API)

Алгоритм одного прохода (reconcile_plane_once())

для каждого проекта p в projects.PROJECTS:
    states = get_project_states(p.plane_project_id)
    for issue in list_issues_by_state(p.plane_project_id,
                                      [states['in_progress'], states['approved'], states['rejected']]):
        task = get_task_by_plane_id(issue.id)
        new_state = issue.state
        # идемпотентность: пропускаем, если есть активный job (живой webhook вот-вот придёт/в работе)
        если task and has_active_job_for_task(task.id):  continue
        # доигрываем потерянный переход ЧЕРЕЗ существующие обработчики plane.py
        if new_state == in_progress and task is None:        -> handle_status_start(issue_data, p.plane_project_id)
        elif new_state == approved and task and stage не сдвинут:  -> handle_verdict(issue_data, ..., approved=True)
        elif new_state == rejected and task and не откатана:       -> handle_verdict(issue_data, ..., approved=False)
        else: continue   # всё синхронно — тишина

• Переиспользовать handle_issue_updated/handle_status_start/handle_verdict из webhooks/plane.py. Они async → reconciler (sync-поток) вызывает их через asyncio.run(...) либо собственный event loop. Способ — на усмотрение архитектора; дублировать логику запрещено.
• issue_data собирается в форму, ожидаемую обработчиками ({"id", "state": {"id":...}, "project", "name", "description_stripped"}). Недостающие поля (name/description) обработчики сами дотягивают через fetch_issue_fields (как сейчас для status-only вебхука).
• Grace для F-2: не реагировать на issue, чей статус сменился совсем недавно (вебхук мог просто задержаться). Источник «давности» — поле времени из Plane (updated_at) и/или локальный grace по tasks.updated_at. Архитектор фиксирует точный критерий «потерян, а не задержан».
• Идемпотентность создания (In Progress без задачи): start_pipeline уже защищён (handle_status_start создаёт только если get_task_by_plane_id пуст). Гонка sweeper↔webhook на создании: оба пройдут проверку «нет задачи» одновременно → возможен дубль. Требование: использовать тот же claim-механизм / уникальность (как ensure_unique_work_item_id + проверка существования под защитой). Архитектор обязан описать atomic-claim на создании в ADR.

list_issues_by_state (новый в plane_sync.py)

• GET {PLANE_BASE}/workspaces/{WORKSPACE}/projects/{pid}/issues/ с фильтром по state (через query-параметр Plane, либо постфильтрация результата по issue.state).
• Пагинация (results + cursor/next) — обойти все страницы.
• Never-raise: при ошибке API/сети → [] + лог warning (Plane outage деградирует мягко, не роняет тик).

4. F-3 — Усиление sha→branch резолва (webhooks/gitea.py::handle_ci_status)

• Текущая цепочка: branches[0].name → git branch -r --contains <sha>. Добавить fallback на БД: если branch не определён, найти task по repo среди активных (stage='development') и, при однозначности, использовать её branch; иначе — оставить неразрезолвленным.
• Заменить logger.debug("could not determine branch...") на logger.info(...) (видимость потери). Sweeper (F-1) всё равно подберёт такую задачу — это defense-in-depth, не критпуть.
• Не менять success/failure-семантику гейта.

5. Конфигурация (src/config.py, env-prefix ORCH_)

Поле	Дефолт	Назначение
reconcile_enabled	True	глобальный kill-switch sweeper'а (self-hosting safety, поэтапный раскат).
reconcile_interval_s	120	период фонового прохода (сек).
reconcile_plane_enabled	True	отдельный флаг для F-2 (опрос Plane API), чтобы можно было гасить только plane-ветку.
reconcile_grace_default_s	600	дефолтный порог «застревания» по tasks.updated_at.
reconcile_grace_overrides_json	""	JSON-объект per-stage порогов, напр. {"analysis": 1800, "development": 300, "deploy": 900}. Невалидный JSON → дефолт (как agent_timeout_overrides_json).
reconcile_notify_unblock	True	слать Telegram при разблокировке (F-4).

grace_for_stage(stage) = override из JSON, иначе reconcile_grace_default_s.

6. БД

• Изменения схемы НЕ требуются (предпочтительно, по образцу merge-gate ORCH-043). Стуковость определяется по существующим tasks.updated_at, tasks.stage и таблице jobs (has_active_job_for_task). update_task_stage уже обновляет updated_at.
• Если архитектор сочтёт необходимым анти-дребезг (tasks.last_reconcile_at) — допускается идемпотентная миграция через _ensure_column (как остальные ALTER в db.py). По умолчанию — без новых колонок.

7. API (опционально, F-4)

• Расширить GET /queue блоком "reconcile": {...} (enabled, interval, last_run_ts, unblocked_total, last_unblocked) — по образцу worker.status().
• ИЛИ добавить GET /reconcile с теми же метриками. Выбор — архитектор. Не обязательно для прохождения AC, но крайне желательно для наблюдаемости.

8. Новые QG checks

• Нет. Sweeper переиспускает существующие гейты из QG_CHECKS через advance_stage. Реестр QG_CHECKS и STAGE_TRANSITIONS не меняются.

9. Артефакты pipeline / документация (обязательно в ЭТОМ PR)

• docs/architecture/README.md — раздел про reconciler (компонент + место в resilience-слое).
• docs/work-items/ORCH-053/06-adr/ADR-001-*.md — архитектурное решение (потоки, гонки, async-вызов обработчиков, подавление спама, grace-критерий, atomic-claim на создании).
• CHANGELOG.md — запись feat: ORCH-053 stuck-task reconciler.
• При желании архитектора — global ADR в docs/architecture/adr/ (сквозной resilience).
• docs/operations/INFRA.md — упомянуть kill-switch ORCH_RECONCILE_ENABLED (self-hosting).

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

• Never-raise в тике: исключение в обработке одной задачи/issue не должно ронять весь проход (изолировать try/except на единицу работы, как queue_worker._drain_once).
• Идемпотентность — см. §2/§3.
• Restart-safe — daemon-поток + threading.Event, чистый stop() в lifespan.finally.
• Тишина при синхронности — нет действий → нет логов уровня INFO/нотификаций.
• Тесты — см. 04-test-plan.yaml (моки Plane/Gitea API и QG, без реальной сети).