--- work_item: ORCH-019 stage: analysis author_agent: analyst status: ready-for-review created_at: 2026-06-10 model_used: claude-opus-4-8 --- # 02 — ТЗ (TRZ): ORCH-019 — Режим багфиксинга (упрощённый/дешёвый трек для багов) Work Item: **ORCH-019** · Repo: **orchestrator** · Стадия: analysis > ТЗ описывает **что** должно измениться и **где** (модули/контракты/артефакты), выведенное из BRD > и фактического кода. **Как** (точная схема: где именно ветвить маршрут, хранить ли тип задачи в > БД, отдельный leaf-модуль или расширение `labels.py`) — решает архитектор в `06-adr/`. ТЗ > фиксирует требования и границы, архитектурное решение не предлагает. > ⚠️ **Корневой инвариант (NFR-1 BRD):** срезается ТОЛЬКО аналитика/архитектура. Любой Quality Gate, > exit-код deploy-хука, под-гейт безопасности/покрытия — байт-в-байт прежние. --- ## 1. Сводка изменения Ввести **опциональный багфикс-трек**: задача, помеченная в Plane меткой `Bug`, проходит конвейер по **укороченному маршруту** — пропускается стадия `architecture` и тяжёлая аналитика (полный BRD/TRZ/AC/ADR заменяются минимальным bug-report + обязательным планом регресс-теста). Все Quality Gate'ы (CI/review/tester/staging/deploy + под-гейты security/merge/coverage/image-freshness) исполняются **без изменений**. Распознавание бага и маршрут — аддитивно, под kill-switch, с областью репо, never-raise, fail-safe → полный цикл. `STAGE_TRANSITIONS` и реестр `QG_CHECKS` структурно не меняются. --- ## 2. Задействованные модули / пути | Путь | Роль в задаче | Характер изменения | |------|---------------|--------------------| | `src/labels.py` | аппарат чтения метки Plane (ORCH-089: `has_label`, `*_applies`) | переиспользовать; **добавить** `is_bug_task(work_item_id, project_id) -> bool` + `bug_fast_track_applies(repo) -> bool` (по образцу `auto_approve_applies`), либо вынести в новый leaf `src/bug_fast_track.py` (never-raise) — выбор архитектора | | `src/plane_sync.py` | `fetch_issue_labels` / `get_project_labels` / `_normalize_label` | **без изменений** — переиспользуются для чтения метки `Bug` (источник истины — Plane API) | | `src/webhooks/plane.py` | `start_pipeline` (создаёт task-row со стадией `"analysis"`, режет ветку `_create_gitea_branch`), `handle_status_start`, `handle_issue_updated` | **ключевая врезка:** перед `create_task_atomic(...)` определить тип задачи и (при багфикс-треке) пометить задачу багом / задать укороченный маршрут. Внешний контракт вебхука Plane не меняется | | `src/stages.py` | `STAGE_TRANSITIONS`, `get_next_stage` | **структура `STAGE_TRANSITIONS` не меняется** (новых стадий нет). Требование: маршрут багфикса = `analysis → development` (пропуск `architecture`). Механизм (условный `get_next_stage` по типу задачи / bug-mode-флаг на task) — архитектору | | `src/stage_engine.py` | `advance_stage`, `_run_qg`, `_handle_analysis_approved_flow`, откаты | `advance_stage` уже маршрутизирует через `get_next_stage` (не зашивает порядок) → при условной маршрутизации правка точечная. Гейты диспетчеризуются как раньше | | `src/db.py` | `create_task_atomic(plane_id, work_item_id, repo, branch, stage, title)`, схема `tasks`, `claim_next_job` | если архитектор решит хранить «тип=bug» в БД — **аддитивная идемпотентная** колонка (`_ensure_column`, напр. `tasks.track TEXT DEFAULT 'full'`); горячий `claim_next_job` **не** должен ходить в сеть (NFR-4) | | `src/config.py` | флаги фичи | новые: `bug_fast_track_enabled`, `bug_fast_track_label`, `bug_fast_track_repos` (CSV) + helper `applies(repo)` по образцу `auto_label_*` / `serial_gate_*` | | `src/qg/checks.py` | реестр `QG_CHECKS` и `check_*` | **без изменений** (инвариант NFR-1) | | `src/serial_gate.py`, `src/coverage_gate.py`, `src/merge_gate.py` | композиция | **без изменений**; проверить совместимость (NFR-7) интеграционным тестом | | `src/main.py` | `GET /queue` | **аддитивный** read-only блок `bug_fast_track` (флаг/область/счётчики/метрика экономии) | | `src/notifications.py` | live-карточка | опционально — отметка «🐞 багфикс-трек» в карточке (never-raise) | | `.openclaw/agents/analyst.md` | промпт мини-аналитика | при багфикс-треке выдавать **облегчённый** пакет (bug-report + регресс-тест-план), не полный BRD/TRZ/AC. Канон промптов 52d не нарушать | | `.openclaw/agents/reviewer.md` | ось контроля | добавить ось «багфикс без регресс-теста → REQUEST_CHANGES» (BR-4) — нормативно-описательно, не машинный гейт | --- ## 3. Функциональные требования ### FR-1 — Классификация задачи как «баг» (BR-1) - Багфикс-трек активируется, если issue несёт метку Plane с именем `bug_fast_track_label` (дефолт `Bug`), прочитанную через `labels.has_label(work_item_id, label, project_id)` (ORCH-089: `fetch_issue_labels` + `get_project_labels`, нормализация `_normalize_label`, TTL-кэш). - **Источник истины — Plane API**, не payload вебхука (поле `type` в payload отсутствует). - Чтение метки допускается **только** в `start_pipeline` (момент старта, сетевой вызов приемлем, как ORCH-089) — **не** в горячем `claim_next_job` (NFR-4). - `applies(repo)` (локальный, без сети) проверяется **первым**; `has_label` (сеть) — только при `applies==True` → при выключенном флаге нулевой сетевой оверхед (образец ORCH-089). ### FR-2 — Укороченный маршрут (BR-2) - Для багфикс-задачи маршрут конвейера: `analysis(lite) → development → review → testing → deploy-staging → deploy → done`, т.е. **пропускается стадия `architecture`** (и её exit-гейт `check_architecture_done` / требование `06-adr/`). - `STAGE_TRANSITIONS` **не изменяется структурно**. Требуемый инвариант результата: при выходе багфикс-задачи из `analysis` следующая стадия = `development` (а не `architecture`); для не-багфикс задач — прежняя `architecture`. Конкретный механизм (условный `get_next_stage(stage, task)` / bug-mode-флаг на task / точка входа сразу в `development`) — решение архитектора. - Тяжёлая аналитика облегчается: на багфикс-треке обязательны лишь `01-brd.md` (короткий bug-report: симптом, шаги воспроизведения, локализация, причина) и `04-test-plan.yaml` (план регресс-теста). Полные `02-trz.md`/`03-acceptance-criteria.md` и `06-adr/` — **не обязательны**. (Совместимость с `check_analysis_complete`, требующим `01/02/03/04` — см. FR-6.) ### FR-3 — Гейты качества сохраняются полностью (BR-3, корневой инвариант) - На багфикс-треке исполняются **без изменений**: `check_ci_green` (development→review), `check_reviewer_verdict` (review→testing, `12-review.md`), `check_tests_passed` (testing→ deploy-staging, `13-test-report.md`), `check_staging_status`, `check_deploy_status`, под-гейты ребра `deploy-staging→deploy` (security ORCH-022 → merge ORCH-043 → coverage ORCH-027 → image-freshness ORCH-058) и merge-verify ребра `deploy→done` (ORCH-071/073). - Ни один `check_*`, его сигнатура, вердикт-ключ или порядок под-гейтов **не меняется**. ### FR-4 — Обязательный регресс-тест (BR-4) - Багфикс **обязан** содержать новый/изменённый тест, воспроизводящий дефект (красный до фикса, зелёный после). Требование закрепляется: (а) в `04-test-plan.yaml` багфикса как обязательный TC; (б) reviewer-осью (`.openclaw/agents/reviewer.md`): «исправление кода без теста-фиксатора → finding ≥P1 / REQUEST_CHANGES»; (в) усиливается coverage-гейтом ORCH-027 (структурно ловит «код без тестов»). Это требование, не новый машинный гейт. ### FR-5 — Эскалация в полный цикл (BR-5) - Багфикс-задача должна иметь путь возврата в полный цикл, если баг оказался сложным/архитектурным или визуальным (нужен макет — связка ORCH-12/14, прецедент ET-9). Минимум v1: ручная эскалация (оператор снимает метку `Bug` / переводит стадию) **и/или** решение мини-аналитика «баг сложный → не фаст-трекать» (тогда задача идёт штатным маршрутом с `architecture`). Конкретный механизм и его автоматизация — архитектору; v1 не обязан включать LLM-авто-триаж сложности. ### FR-6 — Fail-safe → полный цикл (BR-6, NFR-3) - При `bug_fast_track_enabled=False`, неприменимом репо, ошибке/таймауте/неоднозначности чтения метки (`has_label` → False / `None`-labels), отсутствии метки `Bug` в проекте — задача идёт **полным** циклом (точка входа `analysis`, маршрут с `architecture`). never-raise: ошибка логики не роняет `start_pipeline`/вебхук. - **Совместимость с `check_analysis_complete`** (требует наличие `01/02/03/04`): при облегчённом пакете багфикса гейт не должен ложно блокировать. Варианты (архитектору): мини-аналитик всё равно эмитит заглушки `02/03` ИЛИ гейт `check_analysis_approved` на багфикс-треке учитывает облегчённый набор. Требование: **не ослабить** проверку для не-баг задач и **не заблокировать ложно** баг. ### FR-7 — Наблюдаемость стоимости (BR-7) - Факт «задача на багфикс-треке» и метрика экономии видны: (а) аддитивный блок `bug_fast_track` в `GET /queue` (флаг/область + счётчик задач на треке + агрегат сэкономленных стадий/agent-runs); (б) лог-строка на решение о маршруте; (в) опц. отметка в Telegram-карточке. Метрика «во сколько дешевле» считается из существующей телеметрии `agent_runs` (Σ токены/время багфикс-трека vs средний полный цикл) — без новой тяжёлой инфраструктуры. --- ## 4. Изменения API ### 4.1. Новые публичные endpoint'ы - **Не требуются обязательно.** (Эскалация и классификация идут через Plane-метки/статусы, не через новый HTTP-эндпоинт. Если архитектор вводит админ-эндпоинт принудительной (де)классификации — описать в ADR и обновить таблицу API в README.) ### 4.2. Изменяемые endpoint'ы - `GET /queue` — **аддитивно** добавляется блок `bug_fast_track` (read-only, never-raise) по образцу блоков `serial_gate` / `auto_labels` / `coverage`: `enabled`, `repos`, `label`, перечень/счётчик задач на багфикс-треке, агрегатная метрика экономии. Существующие ключи `GET /queue` не меняются. ### 4.3. Webhook-обработчики - `start_pipeline` (`webhooks/plane.py`): добавляется ветвление «issue имеет метку `Bug` и `applies(repo)` → багфикс-трек (пометить задачу / задать укороченный вход-маршрут)». Внешний контракт вебхука Plane не меняется. --- ## 5. Изменения схемы БД > Только **аддитивные, идемпотентные** миграции (общая прод-БД; enduro не трогать). - **Опционально (выбор архитектора):** если тип задачи нужно знать после старта (для маршрутизации в `advance_stage`/`get_next_stage` и для метрики), ввести аддитивную колонку `tasks.track TEXT DEFAULT 'full'` (значения `full` | `bug`) через `_ensure_column` (паттерн `tasks.cancelled_at` ORCH-090). Тогда горячий `claim_next_job` читает тип из БД, **не** из сети (NFR-4). Альтернатива без колонки (вывести тип повторным чтением метки) допустима, но повторный сетевой вызов в горячем пути запрещён (NFR-4) → колонка предпочтительнее. - **Существующие** `tasks`-контракт (прочие колонки), `jobs`, `job_deps`, `agent_runs`, `coverage_baseline`, `repo_freeze` — **без изменений**. --- ## 6. Требования к новым/изменённым QG checks - **Новых QG-проверок не вводить; ни один `check_*` не менять семантически** (NFR-1). Маршрутизация багфикса — свойство планировщика/точки входа, **не** Quality Gate. - Единственная допустимая тонкая правка — обеспечить, чтобы exit-гейт стадии `analysis` (`check_analysis_approved` / helper `check_analysis_complete`) **не блокировал ложно** облегчённый багфикс-пакет, **не ослабляя** проверку для полного цикла (FR-6). Если для этого требуется правка `check_*` — она должна сохранить вердикт-семантику для не-баг задач байт-в-байт. --- ## 7. Совместимость / регресс - **Kill-switch** `bug_fast_track_enabled` (env `ORCH_BUG_FAST_TRACK_ENABLED`); `False` → точка входа и маршрут строго прежние (`analysis → architecture → …`), нулевая регрессия (NFR-2). - **Область репо** `bug_fast_track_repos` (CSV; пусто → рекомендуется self-hosting + явно разрешённые проекты, где есть метка `Bug` — решение об области по умолчанию фиксирует архитектор). - **`applies(repo)` первым** (локально, без сети) → выключенный флаг = нулевой сетевой оверхед, enduro не затронут. - **Композиция (NFR-7):** не конфликтует с serial-gate (ORCH-088: багфикс-задача — обычная задача репо, учитывается в serial-очереди), auto-label (ORCH-089: `autoApprove`/`autoDeploy` работают и на багфикс-треке), coverage-gate (ORCH-027: союзник BR-4), merge-gate (ORCH-043). - **never-raise / fail-safe** (NFR-3): ошибка классификации/маршрута → полный цикл, не падение. - **Self-hosting** (NFR-6): механизм не рестартит/не роняет прод, не пушит/force-push в `main`. - **Маркеры трассировки** (CLAUDE.md §9): новые инварианты помечаются `ORCH-019`; правка маркированного кода (ORCH-088/089/027) — со сверкой их `06-adr/`. --- ## 8. Артефакты pipeline (создать/обновить в ТОМ ЖЕ PR) - `docs/work-items/ORCH-019/06-adr/ADR-001-.md` — решение (механизм маршрута, хранение типа, совместимость с `check_analysis_complete`, область по умолчанию, механизм эскалации). - `docs/architecture/README.md` — новый раздел «Багфикс-трек (ORCH-019)» + блок `bug_fast_track` в описании `GET /queue`; при новой колонке — раздел «База данных». - `CLAUDE.md` — краткий абзац о багфикс-режиме (правила для агентов / конвейер). - `CHANGELOG.md` — запись `feat:`. - `.openclaw/agents/analyst.md` / `reviewer.md` — облегчённый пакет багфикса + reviewer-ось регресс-теста (канон 52d не нарушать). - При новой колонке — `docs/work-items/ORCH-019/08-data-requirements.md` (заполняет архитектор). --- ## 9. Открытые вопросы для архитектора (не блокируют анализ) - OQ-1: Механизм пропуска `architecture` — условный `get_next_stage(stage, task)`, bug-mode-флаг на task, или прямой вход багфикса сразу в `development` с сохранённым мини-bug-report? (Влияет на §3 `stages.py`/`stage_engine.py` и на `check_analysis_complete`.) - OQ-2: Хранить ли тип задачи в БД (`tasks.track`) vs выводить из метки. Рекоменд. — колонка (NFR-4 запрещает сеть в горячем claim). - OQ-3: Сохранять ли мини-стадию `analysis(lite)` (рекоменд., ради регресс-теста и трассируемости) или допустить чистый hotfix `→ development` (вне дефолта). См. BRD §6. - OQ-4: Механизм эскалации (BR-5) — только ручной (снять метку/сменить стадию) или авто-сигнал мини-аналитика «баг сложный → полный цикл». - OQ-5: Область по умолчанию (пустой CSV) — self-hosting only vs все репо с меткой `Bug`. - OQ-6: Совместимость с `check_analysis_approved`/`check_analysis_complete` на облегчённом пакете (FR-6) — заглушки `02/03` vs условный учёт гейтом.