179 lines
19 KiB
Markdown
179 lines
19 KiB
Markdown
---
|
||
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>
|