---
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 +
  интеграционный тест композиции.
</content>
</invoke>
