orchestrator/docs/work-items/ORCH-073/01-brd.md

01 — BRD: ORCH-073 — CRIT: эрозия main (код ORCH-067/069 затёрт ребейзами, не доехал)

• Work Item: ORCH-073
• Тип: BUG CRITICAL — целостность main, накопительный регресс/эрозия
• Репозиторий: orchestrator (self-hosting)
• Ветка: feature/ORCH-073-crit-main-orch-067-069
• Связь: усиливает/чинит ORCH-071 (merge-verify); НЕ покрыт ORCH-071.

1. Бизнес-проблема

Код успешно «задеплоенных» и переведённых в done задач ORCH-067 (tracker bump, Plane-статусы, кликабельные ссылки plane_issue_link) и ORCH-069 (qg0_title_max) физически отсутствовал в origin/main, хотя обе прошли весь конвейер, Confirm Deploy, merge-verify CONFIRMED и стали done. В main попадали только их docs-коммиты (staging-log / verdict через отдельные авто docs-PR), но НЕ код feature-веток.

Внешнее проявление (нашёл Слава, 08.06): «ссылок на задачу в Plane нет», карточка Telegram показывает сырой номер задачи вместо кликабельной ссылки — потому что код ссылок есть в ветке ORCH-067, но не в main.

Накопительный характер: каждая новая задача срезает ветку от УСТАРЕВШЕГО main и при merge тихо (без конфликт-маркеров) затирает код предшественника. Уже потеряны ORCH-067 и ORCH-069; без системного фикса теряется код каждой следующей задачи с правкой CHANGELOG.md.

2. Подтверждённый root cause (git-аудит 08.06, не гипотеза)

1. verify_merged_to_main подтверждает merge по ложному признаку. src/merge_gate.py::verify_merged_to_main возвращает True, если выполнено ЛИБО pr_already_merged(repo, branch), ЛИБО git merge-base --is-ancestor <sha> origin/main. Первая ветка (pr_already_merged) и есть дыра.
2. pr_already_merged засчитывает ЛЮБОЙ merged PR ветки. src/merge_gate.py::pr_already_merged делает GET /pulls?state=all&head=<branch> и возвращает True, если хоть один PR merged==True. У одной ветки несколько PR (code-PR + авто docs-PR со staging/deploy-логами). Сливается docs-PR → функция говорит «already-merged» → verify_merged_to_main=True → merge-verify CONFIRMED → done, хотя code-PR НЕ слит. Ложно-зелёный.
3. CHANGELOG.md-ребейзы — вторичный усилитель. Merge-gate auto_rebase_onto_main при конфликте CHANGELOG.md откатывает deploy-staging → development; повторный ребейз ветки от старого main несёт устаревшие версии файлов (notifications.py/config.py/webhooks/plane.py), которые при merge тихо затирают соседний код (фантом-эффект, как в ORCH-071, без конфликт-маркеров).

Уточнение для архитектора: в ТЗ упомянута «инвертированная проверка merge-base --is-ancestor origin/main HEAD (merge_gate.py ~76)» — это branch_is_behind_main (детектор «ветка свежая»), он корректен для своей цели. Фактический дефект merge-verify — это OR-ветка pr_already_merged в verify_merged_to_main (строка ~649), которая засчитывает docs-PR.

3. Состояние на момент анализа (G1)

Аудит origin/main показал, что восстановительный PR #76 (restore(main): re-merge ORCH-067 + ORCH-069 (ORCH-073)) уже вернул код в main:

• plane_issue_link присутствует (src/notifications.py), qg0_title_max присутствует (src/config.py, src/webhooks/plane.py), verify_merged_to_main присутствует.

Таким образом G1 (восстановление кода) фактически выполнено ручным restore-PR. Задача ORCH-073 должна подтвердить и зафиксировать это в критериях приёмки (AC-1) и сосредоточиться на системном фиксе навсегда (G2–G5 / FR-1…FR-5), иначе регресс повторится.

4. Цели (Goals)

• G1. КОД ORCH-067 и ORCH-069 присутствует в origin/main одновременно с ORCH-071 (подтвердить restore-PR #76, зафиксировать маркеры > 0). Pytest зелёный. Прод задеплоен.
• G2 (FR-2/FR-3). merge/pr_already_merged различают code-PR и docs-PR — merge засчитывается только за PR с кодом ветки (base==main, head==<feature-branch>).
• G3 (FR-1, ядро). verify_merged_to_main подтверждает merge ТОЛЬКО по факту «deployed SHA — предок origin/main». PR-флаги вспомогательны, не достаточны.
• G4 (FR-4). Защита от CHANGELOG-затирания: .gitattributes с CHANGELOG.md merge=union (+ опц. docs/*.md merge=union для append-only).
• G5 (FR-5, регресс-гард навсегда). После деплоя — sanity-проверка целостности main: deployed SHA в main И набор маркеров ранее-merged задач не уменьшился. Откат соседнего кода → alert «main regressed», задача НЕ done.

5. Не-цели (Out of scope)

• Не менять Plane / схему БД.
• Не отменять self-hosting safety (не ронять прод, merge только через PR-API, без force-push в main).
• Не менять ручной гейт Confirm Deploy.
• Не менять поведение merge/verify для non-self репозиториев (enduro-trails) — обратная совместимость.

6. Инварианты

• INV-1. never-raise на верификации (alert, не падение).
• INV-2. self-hosting safety: прод не падает; merge только PR-API, без force-push в main.
• INV-3. ручной Confirm Deploy сохранён.
• INV-4. Идемпотентность: повторный прогон / reaper не делает второй merge; idempotency опирается на «SHA-в-main», а не на «любой merged PR».
• INV-5. Обратная совместимость non-self (enduro): поведение merge/verify без изменений.

7. Заинтересованные стороны

• Owner / Слава — потребитель (видит кликабельные ссылки в карточке; доверие к merge-verify).
• Все проекты на инстансе (enduro-trails) — общий main/очередь/БД; регресс орка = групповой риск.

8. Срочность

КРИТИКАЛ. Без FR-1/FR-4/FR-5 каждая новая задача с правкой CHANGELOG.md продолжает терять код предшественников (уже потеряны 067, 069). Ложно-зелёный merge-verify подрывает само ядро автономности конвейера.