19 KiB
19 KiB
work_item, stage, author_agent, status, created_at, model_used
| work_item | stage | author_agent | status | created_at | model_used |
|---|---|---|---|---|---|
| ORCH-019 | analysis | analyst | ready-for-review | 2026-06-10 | 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/complexLLM-аналитиком — будущее развитие; 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 + интеграционный тест композиции.