analyst(ET): auto-commit from analyst run_id=557

docs/work-items/ORCH-019/01-brd.md

@@ -0,0 +1,178 @@
+---
+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>