--- work_item: ORCH-019 stage: analysis author_agent: analyst status: ready-for-review created_at: 2026-06-10 model_used: claude-opus-4-8 --- # 01 — BRD (бизнес-требования): ORCH-019 — Режим багфиксинга (упрощённый/дешёвый трек для багов) Work Item: **ORCH-019** · Repo: **orchestrator** (self-hosting) · Стадия: analysis Заказчик: Слава · Тип: фича (новый режим конвейера, опциональный, под флагом) > ⚠️ **Принцип, заданный Владельцем (нерушимый):** упрощаем **аналитику**, но **НЕ ослабляем > качество**. Гейты CI / review / tester verdict / deploy verdict **остаются**. Горький урок > ET-8 / BUG-TESTS-SUBSTRING: срезанная *проверка* = недоделка на проде. «Дешевле ≠ > бесконтрольнее». Этот принцип — корневой инвариант всей задачи (см. NFR-1, BR-6). --- ## 1. Бизнес-контекст и проблема ### 1.1. Цель Дать оркестратору **отдельный удешевлённый трек для багфиксов**. Сейчас любой баг (пример: зашёл на карту enduro-trails, увидел дефект, завёл задачу) идёт по **полному** конвейеру `analysis → architecture → development → review → testing → deploy-staging → deploy`. Для мелкой правки полный цикл **избыточен**: лишние стадии (полный BRD/TRZ/AC + архитектурный ADR) тратят токены и время, не добавляя ценности на однострочном фиксе. ### 1.2. Установленные факты (проверено по коду, не изобретать) - **Точка входа задачи в конвейер:** `src/webhooks/plane.py::start_pipeline` создаёт task-row с **жёстко зашитой** начальной стадией `"analysis"` (`create_task_atomic(..., "analysis", ...)`) и режет ветку (`_create_gitea_branch`). Это единственная точка, где задаётся точка входа. - **Маршрутизация стадий полностью управляется** `src/stages.py::STAGE_TRANSITIONS` через `get_next_stage` — `advance_stage` (`src/stage_engine.py`) не содержит «зашитого» порядка стадий, он спрашивает `get_next_stage`. → Изменение точки входа / маршрута локализуемо, машину стадий ломать не нужно. - **Метка задачи уже читается из Plane** аппаратом ORCH-089: `src/labels.py::has_label` + `plane_sync.fetch_issue_labels` / `get_project_labels` (TTL-кэш, нормализация имени, never-raise, fail-safe → False). Источник истины — Plane API, **не** payload вебхука (`type`/`priority` в payload отсутствуют). Это готовый, проверенный шаблон классификации задачи. - **Все Quality Gate'ы читают вердикт из артефактов**, а не из стадии входа: `check_ci_green`, `check_reviewer_verdict` (`12-review.md`), `check_tests_passed` (`13-test-report.md`), `check_staging_status`, `check_deploy_status`, под-гейты security/merge/coverage/image-freshness. Они **не зависят** от того, прошла ли задача `analysis`/`architecture`, → их можно сохранить нетронутыми при срезанном «входе». - **Coverage-гейт (ORCH-027)** уже структурно ловит «код без тестов» на ребре `deploy-staging → deploy` — союзник принципа «баг фиксируется тестом». - **Прецедент стоимости:** UI z-index баг ET-9/ET-014 прошёл **полный** цикл ~35 мин — типичный кандидат на удешевление. ### 1.3. Связки и разграничение - **ORCH-13 (роутинг моделей):** «дешёвая модель на багфиксе» (Вариант 4 постановки) — **вне объёма** ORCH-019, отдельная задача; ORCH-019 лишь оставляет точку композиции (флаг bug-track наблюдаем, по нему ORCH-13 позже может выбрать модель). См. §2.2. - **ORCH-088 (serial gate) / ORCH-089 (auto-label):** ORCH-019 **сосуществует** с ними и переиспользует их аппарат (label-чтение, per-repo flag, claim-gate); не конфликтует. - **ORCH-12 / ORCH-14 (UX) / ET-9 (визуальные баги):** часть багов визуальные и может требовать мини-макета — для таких случаев предусмотрен механизм **эскалации обратно в полный цикл** (BR-5), а не слепое удешевление. - **ORCH-8 (петля уроков):** баг, найденный на проде, — сигнал петли уроков; ORCH-019 этого не меняет (post-deploy-телеметрия ORCH-021 сохраняется). --- ## 2. Объём (scope) ### 2.1. В объёме - **BR-1 — Классификация «баг».** Задача распознаётся как баг по **метке Plane** (рекоменд. имя `Bug`), читаемой аппаратом ORCH-089. Операторская, детерминированная, обратимая разметка. - **BR-2 — Упрощённый трек.** Багфикс-задача идёт по **укороченному** пути: пропускается **тяжёлая аналитика и стадия `architecture`** (полный BRD/TRZ/AC/ADR не требуются); вместо них — **минимальный набор артефактов** (короткий bug-report + обязательный план регресс-теста). - **BR-3 — Гейты качества сохраняются ПОЛНОСТЬЮ.** CI (`check_ci_green`), review (`check_reviewer_verdict`), testing (`check_tests_passed`), staging/deploy-вердикты и под-гейты (security/merge/coverage/image-freshness) исполняются **без изменений** на багфикс-треке. - **BR-4 — Обязательный регресс-тест.** Багфикс **обязан** зафиксировать дефект тестом (тест, падающий до фикса и зелёный после) — главный предохранитель от рецидива (урок ET-8). - **BR-5 — Эскалация в полный цикл.** Если баг оказался сложным/архитектурным или визуальным (нужен макет), он **возвращается** в полный цикл; багфикс-трек не «застревает» на сложном. - **BR-6 — Безопасность по умолчанию (fail-safe → полный цикл).** Любая неоднозначность/ошибка чтения метки/выключенный флаг → задача идёт **полным** циклом (никогда не «теряет» стадии молча). - **BR-7 — Наблюдаемость стоимости.** Виден факт «задача на багфикс-треке» и метрика экономии (стадии/agent-runs/токены/время) относительно полного цикла. ### 2.2. Вне объёма (явно не делать) - **Роутинг моделей (ORCH-13 / Вариант 4):** выбор дешёвой модели на багфиксе — отдельная задача. - **Авто-триаж сложности аналитиком (полный Вариант 3):** автоматическая classification `trivial/small/complex` LLM-аналитиком — будущее развитие; v1 опирается на явную метку оператора + ручную/мини-эскалацию (BR-5), не на ML-классификатор. - **Изменение `STAGE_TRANSITIONS` (новые стадии), реестра `QG_CHECKS`, семантики любого `check_*`, вердикт-ключей** (`verdict:`/`result:`/`deploy_status:`/`staging_status:`/`security_status:`/ `coverage_status:`). - **Параллелизм багфиксов**, изменение `max_concurrency`, merge-очередь. - **Полный отказ от стадии `analysis`** (вариант «hotfix → сразу development») как дефолт — см. §6 (требуется минимальный аналитический проход ради регресс-теста и трассируемости). Чистый hotfix без аналитики оставлен как возможная опция архитектора, но не дефолт. --- ## 3. Заинтересованные стороны - **Владелец/оператор (Слава):** ставит метку `Bug`, получает быстрый дешёвый фикс, эскалирует сложный баг, читает метрику экономии. - **Self-hosting прод (`orchestrator`) и enduro-trails:** общий инстанс/БД/очередь — режим обязан быть аддитивным, под флагом, per-repo, с нулевой регрессией при выключении (FR-условие). - **Агенты конвейера (analyst/developer/reviewer/tester):** работают по тем же контрактам; на багфикс-треке analyst выдаёт облегчённый пакет, остальные — как обычно. --- ## 4. Бизнес-требования (BR) — сводная таблица | ID | Требование | Связь | |----|------------|-------| | BR-1 | Задача распознаётся как баг по метке Plane (`Bug`), читаемой через аппарат ORCH-089 (`labels.has_label` + `plane_sync.fetch_issue_labels`). Источник истины — Plane API, не payload. | FR-1, AC-1 | | BR-2 | Багфикс-задача пропускает тяжёлую аналитику и стадию `architecture`; маршрут `analysis(lite) → development → review → testing → deploy-staging → deploy`. Полный BRD/TRZ/AC/ADR не обязателен. | FR-2, AC-2 | | BR-3 | Все Quality Gate'ы (CI/review/tester/staging/deploy + под-гейты security/merge/coverage/image-freshness) исполняются на багфикс-треке **без изменений**. | FR-3, AC-3 | | BR-4 | Багфикс обязан содержать **регресс-тест** (падает до фикса, зелён после); отсутствие нового/изменённого теста на исправление — повод для REQUEST_CHANGES reviewer'ом. | FR-3/FR-4, AC-4 | | BR-5 | Существует механизм **эскалации** багфикса в полный цикл (сложный/архитектурный/визуальный баг) — задача возвращается на полную аналитику/архитектуру. | FR-5, AC-5 | | BR-6 | **Fail-safe:** при выключенном флаге, ошибке/неоднозначности чтения метки, неприменимом репо — задача идёт **полным** циклом (никогда не теряет стадии молча). never-raise. | FR-6, AC-6 | | BR-7 | Факт багфикс-трека и метрика экономии (пропущенные стадии / Σ agent-runs / токены / время vs полный цикл) наблюдаемы (`GET /queue` блок + лог/Telegram-карточка). | FR-7, AC-7 | | BR-8 | Поведение управляется kill-switch'ом и областью репо (как ORCH-35/43/58/88/89): выключение флага → строго прежнее поведение (нулевая регрессия для enduro и для orchestrator). | NFR-2, AC-6 | --- ## 5. Нефункциональные требования (NFR) | ID | Требование | |----|------------| | NFR-1 | **Качество не ослабляется (корневой инвариант).** Срезается только *аналитика/архитектура*; ни один Quality Gate, exit-код deploy-хука, под-гейт безопасности/покрытия — не ослаблен и не пропущен. | | NFR-2 | **Нулевая регрессия / аддитивность.** При `bug_fast_track_enabled=False` или неприменимом репо путь старта и маршрут идентичны текущим. `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/вердикт-ключи/схема БД — не меняются (допустима лишь аддитивная идемпотентная миграция, если архитектор сочтёт нужным помечать тип задачи в БД). | | NFR-3 | **never-raise / fail-safe.** Любая ошибка классификации/маршрутизации → деградация на полный цикл, не падение вебхука/конвейера (по образцу `labels.py`/`serial_gate.py`). | | NFR-4 | **Offline-устойчивость горячего пути.** Классификация может ходить в Plane API только в момент `start_pipeline` (как ORCH-089), но **не** в горячем `claim_next_job` (иначе встанет очередь всех проектов). | | NFR-5 | **Per-repo область.** Режим включается по CSV-области репо; orchestrator и enduro управляются независимо. | | NFR-6 | **Self-hosting безопасность.** Механизм не рестартит/не роняет прод-контейнер, не пушит/force-push в `main`. | | NFR-7 | **Композируемость.** Корректно сосуществует с serial-gate (ORCH-088), auto-label (ORCH-089), coverage-gate (ORCH-027), merge-gate (ORCH-043). | --- ## 6. Допущения и ограничения - **Минимальный аналитический проход сохраняется** (а не «hotfix → сразу dev»): ради (а) фиксации регресс-теста как контракта приёмки (BR-4), (б) трассируемости (минимальный bug-report). Полный отказ от `analysis` для багов оставлен архитектору как опция, но дефолт — мини-анализ. Обоснование: урок ET-8 — именно отсутствие явного теста-фиксатора привело к «недоделка в Done». - **Классификация v1 — явная метка оператора**, не LLM-авто-триаж (Вариант 3 в полном объёме — будущее). Метка `Bug` должна существовать в Plane-проекте; её отсутствие = fail-safe полный цикл. - **Эскалация v1** — допускает как минимум ручной путь (снять метку `Bug` / вернуть стадию) и/или решение мини-аналитика «баг сложный → не фаст-трекать». Конкретный механизм — архитектору. - **Стоимость измеряется относительно**: метрика «во сколько раз дешевле» считается по факту из существующей телеметрии `agent_runs` (стадии/токены/время), без новой тяжёлой инфраструктуры. --- ## 7. Критерии успеха (резюме; детали — `03-acceptance-criteria.md`) - AC-1 — задача с меткой `Bug` распознаётся и помечается как багфикс-трек. - AC-2 — багфикс-задача проходит конвейер, пропустив стадию `architecture` (и тяжёлый BRD/TRZ/AC). - AC-3 — все Quality Gate'ы исполнены на багфикс-треке (CI/review/tester/staging/deploy + под-гейты). - AC-4 — багфикс содержит регресс-тест; его отсутствие даёт REQUEST_CHANGES. - AC-5 — сложный/визуальный баг эскалируется в полный цикл. - AC-6 — при выключенном флаге / ошибке / неприменимом репо — поведение строго прежнее (полный цикл). - AC-7 — факт багфикс-трека и метрика экономии наблюдаемы. --- ## 8. Риски (детали — `10-tech-risks.md`, заполняет архитектор) - R-1: **Срезали лишнее.** Ошибочный пропуск гейта качества → недоделка на проде (ET-8). Митигатор — NFR-1: режется только аналитика/архитектура, гейты структурно нетронуты + тест AC-3. - R-2: **Сложный баг под меткой `Bug`** уходит на фаст-трек и упирается в отсутствие архитектуры → нужна эскалация (BR-5) и/или решение мини-аналитика. - R-3: **Регресс-тест не написан** (developer «забыл») → рецидив бага. Митигатор — BR-4 + reviewer-ось + союзник coverage-gate (ORCH-027). - R-4: **Fail-safe инвертирован** (ошибка → молча срезали стадии) → недоделка. Митигатор — NFR-3 fail-safe строго в сторону полного цикла + тест AC-6. - R-5: **Конфликт с serial-gate/auto-label** при изменённой точке входа. Митигатор — NFR-7 + интеграционный тест композиции.