admin/orchestrator

Fork 0

Files

claude-bot 13739c0b47

CI / test (push) Successful in 46s

Details

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

2026-06-10 03:17:22 +03:00

19 KiB

Raw Blame History

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

19 KiB Raw Blame History Unescape Escape