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

01 — BRD: Telegram live-tracker, режим bump + русификация карточки

Work Item: ORCH-042 Тип: UX-улучшение (notifications) Приоритет: средний Запрос: Слава, 05.06. Связь: feat/telegram-live-tracker (Variant B+). Self-hosting: да — правка самого оркестратора, проходит через его же конвейер (общая БД/очередь с enduro-trails). См. docs/operations/INFRA.md.

1. Контекст и проблема

Live-tracker задачи (src/notifications.py) — это ОДНА карточка на задачу в Telegram, которая обновляется на каждом переходе стадии через editMessageText (Variant B+). Так сделано СПЕЦИАЛЬНО, чтобы убить старую проблему «~15 отдельных карточек/дублей на задачу».

Побочный эффект текущего решения: карточка редактируется на месте в истории чата. При активной переписке в чате карточка «тонет» вверху и её неудобно искать — приходится скроллить вверх к старому сообщению, чтобы увидеть актуальный статус задачи.

Дополнительно накопились косметические претензии к тексту карточки: смесь англоязычных меток стадий с русским текстом, неудачная формулировка «Ревью БРД», и финальный технический хвост deployed вместо человекочитаемого «Внедрено».

2. Цель

1. Дать Славе альтернативный режим отображения трекера — bump: при каждом обновлении карточка «падает вниз» свежим сообщением (всегда последняя в чате), но БЕЗ возврата к проблеме дублей (по-прежнему ОДНА карточка на задачу) и БЕЗ спама звуками/пингами.
2. Привести текст карточки к единому русскому виду и поправить формулировки.

3. Заинтересованные лица

• Слава (Owner) — единственный получатель Telegram-уведомлений; принимает UX.
• Агенты конвейера — косвенно: трекер обновляется из notify_*-хелперов на каждой стадии.

4. Требования (бизнес-уровень)

4.1. Режим работы трекера (флаг)

• BR-1. Новый конфиг-флаг ORCH_TRACKER_MODE с двумя значениями:
  • edit — текущее поведение (редактирование на месте). Это ДЕФОЛТ (обратная совместимость, никакой регрессии без явного включения).
  • bump — новый режим «карточка падает вниз».
• BR-2. Неизвестное/пустое значение флага трактуется как edit (безопасный фолбэк, оркестратор не падает).

4.2. Поведение режима bump

• BR-3. При обновлении карточки в режиме bump: старое сообщение удаляется (deleteMessage), отправляется новое (sendMessage), указатель tracker_message_id перенаправляется на новое сообщение. Итог: в чате всегда ровно ОДНА карточка задачи, и она всегда внизу.
• BR-4. Bump тихий: новое сообщение отправляется с disable_notification=true — карточка всплывает внизу, но БЕЗ звука/пинга на каждой стадии (как и сейчас в edit-режиме).
• BR-5. Первое обновление (карточки ещё нет) в режиме bump — просто тихо отправить новое и запомнить id (удалять нечего).

4.3. Устойчивость (критично — не сломать защиту от дублей)

• BR-6. Fallback: если deleteMessage не удался (сообщение старше 48 ч / уже удалено / недоступно) — карточка всё равно отправляется заново, оркестратор НЕ падает.
• BR-7. Любой сбой нотификации (сеть/таймаут/5xx/Telegram-ошибка) НЕ роняет оркестратор (контракт «never raises» сохраняется) и НЕ плодит дубли карточек в пределах одного обновления.
• BR-8. Режим edit после изменений работает строго как раньше — без регрессий (защита от ~15 дублей сохранена).

4.4. Текстовые правки карточки (применяются в ОБОИХ режимах)

• BR-9. Метку «Ревью БРД» заменить на «Подтверждение BRD».
• BR-10. После того как задача переведена в Approved (человеческий gate пройден, время ревью зафиксировано), эмодзи в строке подтверждения BRD заменить на галочку (✅) вместо текущей паузы (⏸️). Пока ждём человека — оставить прежний индикатор ожидания.
• BR-11. Русифицировать метки стадий карточки: Analysis → Анализ, Architecture → Архитектура, Development → Разработка, Review → Код ревью, Testing → Тестирование, Deploy → Внедрение.
• BR-12. В итоговой (последней) строке готовой задачи заменить технический deployed на «Внедрено».

5. Вне scope

• Изменение состава событий, которые шлются ОТДЕЛЬНЫМИ пингами (approve-gate / deploy-fail / agent-fail / error) — остаётся как есть.
• Изменение формата метрик (токены/стоимость/длительность), макета строк, логики «попытка N».
• Любые изменения в Plane-комментариях агентов (usage.build_status_comment).
• Хранение истории карточек / несколько карточек на задачу.

6. Влияние на документацию (golden source)

• CHANGELOG.md — запись в [Unreleased].
• docs/architecture/internals.md (или соответствующая секция про live-tracker) — описать режимы edit/bump и ORCH_TRACKER_MODE.
• .env.example — добавить ORCH_TRACKER_MODE с пояснением.

7. Критерии успеха (резюме)

Слава может выставить ORCH_TRACKER_MODE=bump и видеть актуальную карточку всегда внизу чата, одну на задачу, без звона; при откате на edit (дефолт) поведение неотличимо от текущего; текст карточки полностью русифицирован по BR-9..BR-12. Полные условия PASS/FAIL — 03-acceptance-criteria.md.