Compare commits

...

11 Commits

Author SHA1 Message Date
post-deploy-monitor
91a5336736 docs(ORCH-021): post-deploy HEALTHY/NONE for ORCH-019
All checks were successful
CI / test (push) Successful in 49s
2026-06-10 04:23:32 +03:00
deploy-finalizer
758a732422 deploy(ORCH-036): finalize SUCCESS for ORCH-019
All checks were successful
CI / test (push) Successful in 47s
CI / test (pull_request) Successful in 47s
2026-06-10 04:03:52 +03:00
5ecc870897 tester(ET): auto-commit from tester run_id=562
All checks were successful
CI / test (push) Successful in 50s
CI / test (pull_request) Successful in 52s
2026-06-10 03:58:15 +03:00
69970ecebb reviewer(ET): auto-commit from reviewer run_id=561 2026-06-10 03:58:15 +03:00
50bcae765a feat(bug-fast-track): cheaper/shorter pipeline route for bug-fix tasks (ORCH-019)
A task carrying the Plane `Bug` label takes a shortened route that skips the
`architecture` stage (one opus architect run + ADR + check_architecture_done),
replacing heavy analysis with a lite package (bug-report + mandatory regression
test plan). EVERY Quality Gate / sub-gate runs UNCHANGED — the route is a
scheduler property, not a gate (root invariant NFR-1): STAGE_TRANSITIONS /
QG_CHECKS / check_* / machine-verdict keys are byte-for-byte preserved.

- src/bug_fast_track.py: new leaf (never-raise) — bug_fast_track_applies (local,
  network-free, checked first), is_bug_task (labels.has_label, Plane API source),
  skips_architecture (pure DB-backed routing predicate), snapshot.
- src/db.py: additive idempotent tasks.track column (TEXT DEFAULT 'full') +
  set_task_track / get_task_track helpers (missing/NULL -> 'full', fail-safe).
- src/stage_engine.py: routing-override on the analysis-exit edge (track='bug' ->
  development/developer, skipping architect); brd-review-clock stamp extended to
  analysis->development. get_next_stage/get_agent_for_stage stay pure.
- src/webhooks/plane.py: classify task as bug in start_pipeline (applies-first
  short-circuit; never-raise -> full cycle on any error).
- src/main.py: additive bug_fast_track block in GET /queue + POST
  /bug-fast-track/escalate (reset 'bug'->'full' to return to the full cycle).
- src/config.py: bug_fast_track_enabled / _label / _repos flags (empty CSV ->
  self-hosting only).
- src/notifications.py: optional 🐞 marker on the bug-track card (never-raise).
- Prompts: analyst.md (lite bug package + escalation), reviewer.md (regression-
  test axis) — 52d canon preserved.
- Docs: CLAUDE.md, README.md (env + API + section), docs/architecture/README.md,
  CHANGELOG.md, .env.example.
- Tests: tests/test_bug_fast_track*.py + test_db_migrations.py + queue block
  (TC-01..TC-15). Full regression green (1551 passed).

Kill-switch ORCH_BUG_FAST_TRACK_ENABLED=false -> 1:1 pre-ORCH-019 (zero
regression; residual track column harmless).

Refs: ORCH-019

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-10 03:58:15 +03:00
bc04186b93 architect(ET): auto-commit from architect run_id=558 2026-06-10 03:58:15 +03:00
2dfbdd61aa analyst(ET): auto-commit from analyst run_id=557 2026-06-10 03:58:15 +03:00
5fd9b1a094 docs: init ORCH-019 business request 2026-06-10 03:58:15 +03:00
a14d2cc5c8 docs(ORCH-019): staging gate log — SUCCESS (8/10, C9a/C9b infra-waived) 2026-06-10 03:57:54 +03:00
e2c0b2ba9b Merge pull request 'feat: ORCH-057-bug-follow-up-orch-040-normali' (#113) from feature/ORCH-057-bug-follow-up-orch-040-normali into main
Some checks failed
CI / test (push) Has been cancelled
2026-06-10 03:09:07 +03:00
deploy-finalizer
c30dc71b88 deploy(ORCH-036): finalize SUCCESS for ORCH-057
All checks were successful
CI / test (push) Successful in 44s
2026-06-10 03:09:06 +03:00
39 changed files with 2853 additions and 4 deletions

View File

@@ -139,6 +139,18 @@ ORCH_SERIAL_GATE_FREEZE_ENABLED=true
# for enduro too).
ORCH_STOP_STATUS_ENABLED=true
ORCH_STOP_STATUS_REPOS=
# ORCH-019: bug-fast-track — a cheaper/shorter pipeline route for bug-fix tasks.
# A task carrying the Plane `Bug` label skips the whole `architecture` stage; EVERY
# Quality Gate / sub-gate runs UNCHANGED (route is a scheduler property, not a gate).
# Additive, never-raise, fail-safe -> full cycle. Infra precondition: create a `Bug`
# label on the ORCH board (its absence = full cycle, fail-safe). Leaf src/bug_fast_track.py.
# BUG_FAST_TRACK_ENABLED=false -> start_pipeline AND advance_stage are 1:1 as before
# ORCH-019 (zero regression).
# BUG_FAST_TRACK_LABEL -> Plane label that activates the track (default `Bug`).
# BUG_FAST_TRACK_REPOS (CSV) -> scope; EMPTY = self-hosting only (orchestrator).
ORCH_BUG_FAST_TRACK_ENABLED=true
ORCH_BUG_FAST_TRACK_LABEL=Bug
ORCH_BUG_FAST_TRACK_REPOS=
# ORCH-094: terminal-window-aware guard for the three deploy-phase Plane status
# setters (set_issue_awaiting_deploy / set_issue_deploying / set_issue_monitoring).
# A DB stage=done task converges to Done idempotently instead of flapping

View File

@@ -29,6 +29,17 @@ FastAPI + SQLite, конвейер стадий через Quality Gates, аге
Стандарт структуры документов — `docs/_standards/PIPELINE_DOCS.md`; копируй скелеты из
`docs/_templates/` (`01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`, `04-test-plan.yaml`).
**Багфикс-трек (ORCH-019).** Если задача помечена меткой Plane `Bug` (укороченный маршрут —
пропуск стадии `architecture`), выпускай **облегчённый** пакет, но **всё равно все 4 файла**
(гейт `check_analysis_complete` требует `01/02/03/04` — не меняется): `01-brd.md` = короткий
bug-report (симптом / шаги воспроизведения / локализация / причина), `02-trz.md` +
`03-acceptance-criteria.md` = краткие bug-shaped заглушки, `04-test-plan.yaml` = план
**обязательного регресс-теста** (красный до фикса, зелёный после). Экономия — в пропуске целой
стадии `architecture` (отдельный прогон архитектора + ADR), не в числе файлов. Если баг оказался
**сложным/архитектурным/визуальным** (нужен ADR или макет) — выпусти **полный** analysis-пакет и
помечай в bug-report `escalate: full-cycle` (эскалация в полный цикл, ADR-001 D5 ORCH-019); оператор
снимает багфикс-трек эндпоинтом `POST /bug-fast-track/escalate`.
</task>
<deliverables>

View File

@@ -42,6 +42,11 @@ tools:
(слом критического инварианта конвейера может быть P0). Это усиление оси, а не отдельная ось.
3. **Качество кода** — нет явных ошибок/утечек/security-дыр? Есть docstrings на публичных функциях?
Тесты содержательные (не тривиальные)?
- **Багфикс-трек: регресс-тест (ORCH-019, BR-4).** Если задача — багфикс (метка `Bug` /
укороченный маршрут с пропуском `architecture`), исправление кода **обязано** нести
новый/изменённый тест-фиксатор дефекта (красный до фикса, зелёный после). Фикс кода без
теста-фиксатора → **finding ≥ P1 / REQUEST_CHANGES**. Это усиление оси «качество», а не
отдельная ось (структурно дублируется coverage-гейтом ORCH-027).
4. **Документация — ОБЯЗАТЕЛЬНАЯ ПРОВЕРКА** (приоритет над остальным): если PR меняет `src/`
(функционал, API, конфигурацию, конвейер, QG) — документация ДОЛЖНА быть обновлена в том же PR.
Проверь: API → `docs/architecture/README.md` (таблица API)? стадии/QG →

View File

@@ -3,6 +3,15 @@
Формат: [Keep a Changelog](https://keepachangelog.com/). Записи — на смысловой PR/задачу.
## [Unreleased]
- **Багфикс-трек: упрощённый/дешёвый маршрут конвейера для багов** (ORCH-019, `feat`): задача с меткой Plane `Bug` идёт **укороченным маршрутом** — пропускается стадия `architecture` (отдельный прогон opus-агента `architect` + ADR + exit-гейт `check_architecture_done`), тяжёлая аналитика заменяется облегчённым пакетом (короткий bug-report + обязательный план регресс-теста). **Все Quality Gate'ы исполняются без изменений** (корневой инвариант NFR-1): `STAGE_TRANSITIONS` / реестр `QG_CHECKS` / сигнатуры `check_*` / machine-verdict ключи (`verdict:`/`result:`/`deploy_status:`/`staging_status:`/`security_status:`/`coverage_status:`) — байт-в-байт прежние; маршрутизация багфикса — свойство планировщика, **не** гейт. Аддитивно, под kill-switch, с областью репо, never-raise, fail-safe → полный цикл. ADR: `docs/work-items/ORCH-019/06-adr/ADR-001-bug-fast-track.md`, сквозной `docs/architecture/adr/adr-0032-bug-fast-track.md`.
- **Классификация (D1, FR-1):** новый leaf `src/bug_fast_track.py` (never-raise, паттерн `labels`/`serial_gate`). `bug_fast_track_applies(repo)` (локально, без сети) проверяется ПЕРВЫМ → выключенный флаг = нулевой сетевой оверхед; `is_bug_task(work_item_id, project_id)` делегирует в проверенный `labels.has_label` (ORCH-089: `fetch_issue_labels`+`get_project_labels`, нормализация, TTL-кэш). **Источник истины — Plane API**, не payload вебхука. Чтение метки — только в `start_pipeline`, **никогда** в горячем `claim_next_job` (NFR-4).
- **Хранение типа (D2):** аддитивная идемпотентная колонка `tasks.track TEXT DEFAULT 'full'` (`_ensure_column`, паттерн `tasks.cancelled_at` ORCH-090); значения `'full'` (дефолт, ВСЕ существующие и не-баг задачи) | `'bug'`. Хелперы `db.set_task_track`/`db.get_task_track` (отсутствие/NULL → `'full'`, fail-safe). Сигнатура `create_task_atomic` не меняется.
- **Routing-override (D3, FR-2):** врезка в `advance_stage` на ребре выхода из `analysis`: при `track='bug'` (через чистый предикат `bug_fast_track.skips_architecture`) `next_stage``development`, `next_agent``developer` (минуя `architect`). `get_next_stage`/`get_agent_for_stage`/`STAGE_TRANSITIONS` — чистые, 1:1; тип читается из БД (без сети, NFR-4). Для не-баг задач (`track='full'`) маршрут байт-в-байт прежний. Сопутствующе: стамп `mark_brd_review_ended` расширен на `analysis → development` (честная метрика ORCH-087 на багфикс-треке).
- **Гейт `analysis` не тронут (D4, FR-6):** `check_analysis_complete`/`check_analysis_approved` байт-в-байт прежние; багфикс-аналитик всё равно эмитит все 4 файла (облегчённые) — сильнейшая позиция NFR-1 (нулевая поверхность правок гейта).
- **Эскалация (D5, FR-5):** админ-эндпоинт `POST /bug-fast-track/escalate?work_item=<id>` (по образцу `POST /serial-gate/unfreeze`) сбрасывает `track` `'bug'→'full'` → следующий переход уходит в `architecture` (полный цикл). Плюс решение мини-аналитика «баг сложный → полный пакет + `escalate: full-cycle`».
- **Область / флаги (D6):** `bug_fast_track_enabled` (kill-switch, env `ORCH_BUG_FAST_TRACK_ENABLED`), `bug_fast_track_label` (дефолт `Bug`), `bug_fast_track_repos` (CSV; **пусто → self-hosting only** — enduro подключается явным CSV). `False` → старт и маршрут 1:1 как до ORCH-019 (нулевая регрессия, AC-6).
- **Наблюдаемость (D7, FR-7):** аддитивный read-only блок `bug_fast_track` в `GET /queue` (флаг/метка/область + счётчик багфикс-задач + метрика сэкономленных стадий `architecture`); лог-строка на решение о маршруте; отметка `🐞` в Telegram-карточке (never-raise). Композиция (D8, AC-9): багфикс-задача — обычная задача репо для serial-gate (ORCH-088, не обходит его); `autoApprove`/`autoDeploy` (ORCH-089), coverage-gate (ORCH-027, союзник BR-4), merge-gate (ORCH-043) — штатно.
- **Промпты:** `analyst.md` (облегчённый багфикс-пакет + путь эскалации), `reviewer.md` (ось «багфикс без регресс-теста → finding ≥P1 / REQUEST_CHANGES») — канон 52d не нарушен. **Инфра-предусловие:** создать метку `Bug` в Plane-проекте ORCH (её отсутствие = fail-safe полный цикл). Тесты: `tests/test_bug_fast_track*.py` + `tests/test_db_migrations.py` + блок в `tests/test_queue_endpoint.py` (TC-01…TC-15). Полный регресс `tests/ -q` зелёный. Откат: `ORCH_BUG_FAST_TRACK_ENABLED=false` (мгновенный; остаточная колонка `track` безвредна).
- **Детект legacy root-owned файлов + внятная ошибка worktree при миграции на uid 1000** (ORCH-057, follow-up ORCH-040, `feat`): закрыт недоделанный AC ORCH-040 — legacy `root:root` файлы в `/repos` (после перевода контейнеров на `user: "1000:1000"`) ломали создание worktree под uid 1000 (`ensure_worktree` → сырой `fatal: … Permission denied`, агент не стартовал, диагноза не было). Три аддитивных, обратимых kill-switch'ем слоя; **`STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict-ключи / схема БД — байт-в-байт прежние**. ADR: `docs/work-items/ORCH-057/06-adr/ADR-001-legacy-ownership-normalization.md`, сквозной `docs/architecture/adr/adr-0031-legacy-ownership-normalization.md`.
- **D1 — actionable-ошибка `ensure_worktree`:** класс «нет прав» (`Permission denied` / `could not create leading directories` / `insufficient permission for adding an object` / `PermissionError`/`EACCES`/`EPERM`) оборачивается в `RuntimeError` с **причиной** (legacy root-файлы в `/repos/_wt`/`.git` после миграции uid), **лечащей командой** (`chown -R <uid>:<uid> …`) и ссылкой на `INFRA.md` — вместо сырого git stderr. Ошибки, **не** связанные с правами, сохраняют прежний контракт (меняется только формулировка, не факт сбоя; чистый классификатор `fs_normalize.classify_worktree_error`). Под выключенным kill-switch контракт ошибки 1:1 как до ORCH-057.
- **D2 — детект-леаф `src/fs_normalize.py`** (never-raise, паттерн `serial_gate`/`coverage_gate`): `scan_ownership(roots, target_uid=os.getuid())` обходит `/repos/_wt`, `<repo>/.git/{objects,worktrees}`, `data/runs` с ранним выходом при первом `st_uid != target_uid`, TTL-кэшем (`fs_scan_cache_ttl_s`, по образцу `preflight._cache`) и `applies(repo)` first (пустой CSV → self-hosting only → enduro-trails не сканируется). Опц. `normalize()` chown'ит **только** при `geteuid()==0` (под uid 1000 — no-op + честный лог «нужна операторская процедура», НЕ ошибка).

View File

@@ -153,6 +153,43 @@ created → analysis → architecture → development → review → testing →
`docs/work-items/ORCH-090/06-adr/ADR-001-stop-cancel-task.md`,
`docs/architecture/adr/adr-0026-stop-cancel-task.md`.
## Багфикс-трек: дешёвый маршрут для багов (ORCH-019)
Задача с меткой Plane `Bug` идёт **укороченным маршрутом** — пропускается стадия `architecture`
(отдельный прогон opus-агента `architect` + ADR + exit-гейт `check_architecture_done`); тяжёлая
аналитика заменяется облегчённым пакетом (короткий bug-report + обязательный план регресс-теста,
но всё равно все 4 файла analysis — гейт `check_analysis_complete` не меняется). **Корневой
инвариант (NFR-1):** срезается ТОЛЬКО аналитика/архитектура — **все Quality Gate'ы и под-гейты
исполняются без изменений** (`STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict ключи —
байт-в-байт прежние); маршрутизация багфикса — свойство планировщика, **не** гейт. Аддитивно, под
kill-switch, never-raise, fail-safe → полный цикл.
- **Классификация (D1):** leaf `src/bug_fast_track.py` (never-raise, образец `labels`/`serial_gate`).
`bug_fast_track_applies(repo)` (локально, без сети) ПЕРВЫМ → выключенный флаг = нулевой сетевой
оверхед; `is_bug_task` делегирует в `labels.has_label` (ORCH-089-аппарат, источник истины — Plane
API, не payload). Чтение метки — только в `start_pipeline`, **никогда** в горячем `claim_next_job`
(NFR-4).
- **Хранение типа (D2):** аддитивная идемпотентная колонка `tasks.track TEXT DEFAULT 'full'`
(`_ensure_column`, паттерн `tasks.cancelled_at`); значения `'full'` (дефолт, ВСЕ существующие и
не-баг задачи) | `'bug'`. Хелперы `db.set_task_track`/`get_task_track` (отсутствие/NULL → `'full'`,
fail-safe). Читается в `advance_stage` из БД, не из сети.
- **Routing-override (D3):** врезка в `advance_stage` на ребре выхода из `analysis`: при `track='bug'`
(чистый предикат `bug_fast_track.skips_architecture`) `next_stage``development`, `next_agent`
`developer` (минуя `architect`). `STAGE_TRANSITIONS`/`get_next_stage`/`get_agent_for_stage` — чистые,
1:1. Стамп `mark_brd_review_ended` расширен на `analysis → development` (честная метрика ORCH-087).
- **Эскалация (D5):** `POST /bug-fast-track/escalate?work_item=<id>` сбрасывает `track` `'bug'→'full'`
→ следующий переход уходит в `architecture` (полный цикл). Плюс self-escalate мини-аналитика
(«баг сложный → полный пакет + `escalate: full-cycle`»).
- **Флаги** (`config.py`): `bug_fast_track_enabled` (kill-switch, env `ORCH_BUG_FAST_TRACK_ENABLED`),
`bug_fast_track_label` (дефолт `Bug`), `bug_fast_track_repos` (CSV; **пусто → self-hosting only**).
`False`/неприменимый репо → старт и маршрут байт-в-байт прежние (нулевая регрессия для enduro и
orchestrator). Наблюдаемость — read-only блок `bug_fast_track` в `GET /queue` (флаг/метка/область +
счётчик багфикс-задач + метрика пропущенных стадий `architecture`) + отметка `🐞` в Telegram-карточке
(never-raise). Композиция: багфикс-задача — обычная задача репо для serial-gate (ORCH-088, не
обходит его); `autoApprove`/`autoDeploy` (ORCH-089), coverage-gate (ORCH-027, союзник BR-4),
merge-gate (ORCH-043) — штатно. **Инфра-предусловие:** создать метку **`Bug`** в Plane-проекте ORCH
(её отсутствие = fail-safe полный цикл). Детали —
`docs/work-items/ORCH-019/06-adr/ADR-001-bug-fast-track.md`,
`docs/architecture/adr/adr-0032-bug-fast-track.md`.
## Гейт покрытия тестами (ORCH-027)
Существующие тестовые гейты (`check_ci_green`, `check_tests_passed`, merge-gate re-test) судят
только по **факту** прохождения, не по **полноте** — ни один не замечает «300 строк кода, 0

View File

@@ -45,6 +45,7 @@ created → analysis → architecture → development → review → testing →
| GET | `/queue` | Очередь задач (ORCH-1): counts по статусам + max_concurrency + последние 10 jobs |
| POST | `/webhook/plane` | Plane webhook receiver |
| POST | `/webhook/gitea` | Gitea webhook receiver |
| POST | `/bug-fast-track/escalate?work_item=<id>` | Эскалация багфикс-задачи в полный цикл (ORCH-019): сброс `track` `'bug'→'full'` → следующий переход уходит в `architecture` |
## Структура проекта
@@ -140,6 +141,9 @@ uvicorn src.main:app --reload --port 8500
| `ORCH_QG0_TITLE_MAX` | Верхний лимит длины заголовка QG-0 (вход `_qg0_errors`); невалидное/пустое значение → дефолт (ORCH-069) | `200` |
| `ORCH_STOP_STATUS_ENABLED` | Kill-switch отмены задачи по Plane-статусу **STOP** + закрытия дыры релонча (ORCH-090); `false` → поведение 1:1 как до ORCH-090 | `true` |
| `ORCH_STOP_STATUS_REPOS` | CSV область репо для STOP-отмены; пусто = все репо (ORCH-090) | `""` |
| `ORCH_BUG_FAST_TRACK_ENABLED` | Kill-switch багфикс-трека (ORCH-019): задача с меткой Plane `Bug` пропускает стадию `architecture`; `false` → старт и маршрут 1:1 как до ORCH-019 (нулевая регрессия) | `true` |
| `ORCH_BUG_FAST_TRACK_LABEL` | Имя метки Plane, активирующей багфикс-трек (ORCH-019) | `Bug` |
| `ORCH_BUG_FAST_TRACK_REPOS` | CSV область репо для багфикс-трека; **пусто → self-hosting only** (`orchestrator`) — enduro подключается явным CSV (ORCH-019) | `""` |
## Очередь задач (ORCH-1 / F-2b)
@@ -181,6 +185,36 @@ ORCH-090/06-adr/ADR-001-stop-cancel-task.md` + сквозной
> группой `cancelled`. До создания статуса фича в fail-safe (нет UUID → ветка STOP
> не активируется).
## Багфикс-трек: дешёвый маршрут для багов (ORCH-019)
Задача с меткой Plane `Bug` (имя метки — `ORCH_BUG_FAST_TRACK_LABEL`, дефолт `Bug`)
идёт **укороченным маршрутом** конвейера: `analysis(lite) → development → review →
testing → deploy-staging → deploy → done`, т.е. **пропускается стадия `architecture`**
(отдельный прогон opus-агента `architect` + ADR + exit-гейт `check_architecture_done`).
Мини-аналитик выдаёт облегчённый пакет (короткий bug-report + обязательный план
регресс-теста), но всё равно все 4 файла analysis — гейт `check_analysis_complete`
не меняется.
**Корневой инвариант:** упрощается только аналитика/архитектура — **все Quality
Gate'ы и под-гейты исполняются без изменений** (`STAGE_TRANSITIONS` / `QG_CHECKS` /
`check_*` / machine-verdict ключи — байт-в-байт прежние). Маршрутизация багфикса —
свойство планировщика (routing-override в `advance_stage` по `tasks.track='bug'`),
**не** Quality Gate.
Классификация (`src/bug_fast_track.py`, never-raise): локальный `bug_fast_track_applies(repo)`
ПЕРВЫМ (выключенный флаг = нулевой сетевой оверхед), затем `is_bug_task` через
`labels.has_label` (источник истины — Plane API). Тип хранится в аддитивной колонке
`tasks.track` (`'full'` | `'bug'`), читается в горячем пути из БД (не из сети).
**Эскалация** сложного/архитектурного бага в полный цикл — `POST /bug-fast-track/escalate?work_item=<id>`
(сброс `'bug'→'full'`). Всё под kill-switch `ORCH_BUG_FAST_TRACK_ENABLED`, область —
`ORCH_BUG_FAST_TRACK_REPOS` (пусто → self-hosting only), fail-safe → полный цикл.
Наблюдаемость — блок `bug_fast_track` в `GET /queue` + отметка `🐞` в Telegram-карточке.
Деталь — `docs/work-items/ORCH-019/06-adr/ADR-001-bug-fast-track.md` + сквозной
`docs/architecture/adr/adr-0032-bug-fast-track.md`.
> **Инфра-предусловие:** на доске Plane проекта ORCH создать метку **`Bug`**. До её
> создания фича в fail-safe (нет метки → задача идёт полным циклом).
**Resilience-слой:** дешёвый preflight (CLI/net, кэш, без токенов) гейтит claim;
429/overload детектится по логу (transient vs permanent), transient ретраится с
exp-backoff (`available_at`, Retry-After); circuit breaker паузит воркер после N

View File

@@ -373,6 +373,43 @@ Phase A ждёт ручного `Confirm Deploy`, ORCH-059). ORCH-089 снима
`docs/work-items/ORCH-089/06-adr/ADR-001-auto-label-gates.md`,
`docs/work-items/ORCH-089/07-infra-requirements.md`.
### Багфикс-трек: укороченный маршрут для багов (ORCH-019 — реализовано)
Задача с меткой Plane `Bug` идёт по **укороченному** маршруту `analysis(lite) → development →
review → testing → deploy-staging → deploy → done`, **минуя стадию `architecture`** (отдельный
прогон opus-агента `architect` + ADR + exit-гейт `check_architecture_done`). **Корневой инвариант
(NFR-1):** срезается ТОЛЬКО аналитика/архитектура; ни один Quality Gate / под-гейт
(security/merge/coverage/image-freshness) / вердикт-ключ — НЕ ослаблен (урок ET-8). Аддитивно, под
kill-switch, per-repo, never-raise, fail-safe → полный цикл; `STAGE_TRANSITIONS`/`QG_CHECKS`/
`check_*` — **не трогаются**.
- **Багфикс-трек = свойство планировщика/точки входа, НЕ Quality Gate.** Классификация —
leaf `src/bug_fast_track.py` (never-raise, образец `serial_gate`/`labels`): метка `Bug`
читается аппаратом ORCH-089 (`labels.has_label` + `plane_sync.fetch_issue_labels`), задача
помечается `track='bug'`. `applies(repo)` (локально, без сети) — ПЕРВЫМ; `has_label` (сеть) —
только при `applies==True`; чтение метки **только** в `start_pipeline`, никогда в горячем
`claim_next_job` (NFR-4 anti-stall).
- **Хранение типа** — аддитивная колонка `tasks.track TEXT DEFAULT 'full'` (`_ensure_column`,
паттерн `tasks.cancelled_at` ORCH-090); читается в `advance_stage` из БД, не из сети.
- **Routing-override** — `STAGE_TRANSITIONS`/`get_next_stage`/`get_agent_for_stage` остаются
чистыми (1:1). В `advance_stage` на ребре выхода из `analysis` при `track='bug'`: `next_stage`
→ `development` (вместо `architecture`), `next_agent` → `developer` (вместо `architect`).
- **Гейт `analysis` не трогаем** — `check_analysis_complete`/`check_analysis_approved` байт-в-байт;
lite-аналитик эмитит все 4 файла (01-bug-report / 02-03 краткие заглушки / 04 план обязательного
регресс-теста, BR-4). Экономия — пропуск всей стадии `architecture`, не число файлов.
- **Эскалация** (обратимость BR-5) — `POST /bug-fast-track/escalate?work_item=<id>` сбрасывает
`track→'full'` (+ self-escalate мини-аналитика) → задача идёт через `architecture`.
- **Флаги** (`config.py`): `bug_fast_track_enabled` (kill-switch), `bug_fast_track_label`
(дефолт `Bug`), `bug_fast_track_repos` (CSV; **пусто → self-hosting only**). `False`/неприменимый
репо → путь старта и маршрут **байт-в-байт** прежние (нулевая регрессия для enduro и orchestrator).
- **Наблюдаемость (AC-7):** read-only блок `bug_fast_track` в `GET /queue` (флаг/область/метка +
счётчик `track='bug'` + метрика экономии стадий/agent-runs/токенов/времени из `agent_runs`); лог
на решение о маршруте; опц. `🐞` в Telegram-карточке.
- **Инфра-предусловие:** создать метку `Bug` в Plane-проекте ORCH; её отсутствие = `has_label`
False = полный цикл (fail-safe).
Подробнее: [adr-0032](adr/adr-0032-bug-fast-track.md), детально —
`docs/work-items/ORCH-019/06-adr/ADR-001-bug-fast-track.md`,
`docs/work-items/ORCH-019/08-data-requirements.md`.
### STOP / отмена задачи: терминал `cancelled` + закрытие дыры релонча (ORCH-090 — реализовано)
До ORCH-090 не было штатного способа отменить задачу (ручная хирургия по БД/процессам) и

View File

@@ -0,0 +1,95 @@
---
work_item: ORCH-019
stage: architecture
author_agent: architect
status: proposed
created_at: 2026-06-10
model_used: claude-opus-4-8
---
# adr-0032: Багфикс-трек — укороченный маршрут конвейера для багов (ORCH-019)
## Статус
Proposed
## Контекст
Любая задача идёт по полному конвейеру `analysis → architecture → development → review → testing
→ deploy-staging → deploy → done`. Для мелкого бага стадия `architecture` (отдельный прогон
opus-агента `architect` + ADR + exit-гейт `check_architecture_done`) избыточна и тратит
токены/время (прецедент ET-9/ET-014 ~35 мин).
**Корневой инвариант (нерушимый):** упрощаем только *аналитику/архитектуру*; ни один Quality
Gate / под-гейт (security/merge/coverage/image-freshness) / exit-код deploy-хука — НЕ ослаблен
(урок ET-8: срезанная проверка = недоделка на проде).
Кросс-каттинговость: затрагивает семантику маршрутизации (`advance_stage`), вводит новый
leaf-компонент `src/bug_fast_track.py` и аддитивную колонку `tasks.track` → регистрируется
сквозным ADR.
## Решение
Багфикс-трек — **свойство планировщика/точки входа, НЕ Quality Gate**.
1. **Классификация** (`src/bug_fast_track.py`, leaf never-raise по образцу `serial_gate`/`labels`):
задача с меткой Plane `Bug` (`bug_fast_track_label`, читается аппаратом ORCH-089
`labels.has_label`) помечается `track='bug'`. `applies(repo)` (локально, без сети) — первым;
`has_label` (сеть) — только при `applies==True`; чтение метки **только** в `start_pipeline`,
никогда в горячем `claim_next_job` (anti-stall).
2. **Хранение** — аддитивная идемпотентная колонка `tasks.track TEXT DEFAULT 'full'`
(`_ensure_column`, паттерн `tasks.cancelled_at` ORCH-090); читается в `advance_stage` из БД
(не из сети).
3. **Routing-override**`STAGE_TRANSITIONS` и `get_next_stage`/`get_agent_for_stage` остаются
**чистыми** (1:1). В `advance_stage`, на ребре выхода из `analysis`, при `track='bug'`:
`next_stage``development` (вместо `architecture`), `next_agent``developer` (вместо
`architect`). Багфикс физически минует стадию `architecture` → её exit-гейт
`check_architecture_done` и `06-adr/` для багфикса не исполняются.
4. **Гейт `analysis` не трогаем**`check_analysis_complete`/`check_analysis_approved` байт-в-байт
прежние; lite-аналитик эмитит все 4 файла (01-bug-report / 02-03 краткие заглушки / 04 план
обязательного регресс-теста). Экономия — пропуск всей стадии `architecture`, не число файлов.
5. **Эскалация** (обратимость) — `POST /bug-fast-track/escalate?work_item=<id>` сбрасывает
`track→'full'` (+ self-escalate мини-аналитика); задача далее идёт через `architecture`.
6. **Условность/откат**`bug_fast_track_enabled` (kill-switch), `bug_fast_track_label`,
`bug_fast_track_repos` (CSV; **пусто → self-hosting only**). `False`/неприменимый репо →
путь старта и маршрут **байт-в-байт** прежние.
7. **Наблюдаемость** — read-only блок `bug_fast_track` в `GET /queue` (флаг/область/метка +
счётчик `track='bug'` + метрика экономии из `agent_runs`); лог на решение о маршруте; опц.
`🐞` в Telegram-карточке.
## Кросс-каттинговые инварианты (НЕ нарушаются)
- `STAGE_TRANSITIONS` структурно не меняется (нет новых/удалённых стадий); `cancelled`/`done`
стоки и предикаты терминальности (ORCH-090) не затронуты.
- Реестр `QG_CHECKS`, сигнатуры `check_*`, вердикт-ключи (`verdict:`/`result:`/`deploy_status:`/
`staging_status:`/`security_status:`/`coverage_status:`), порядок под-гейтов — байт-в-байт.
- Врезка ORCH-019 в `advance_stage` — ТОЛЬКО на ребре выхода из `analysis`, ДО всех deploy-edge
под-гейтов (ORCH-022/043/027/058) и Phase A/B (ORCH-036/059) → их инварианты сохранены.
- Композиция с serial-gate (ORCH-088), auto-label (ORCH-089), coverage-gate (ORCH-027),
merge-gate (ORCH-043) — багфикс-задача остаётся обычной задачей репо.
## Последствия
- **+** Багфикс минует стадию `architecture` (основная экономия), гейты качества сохранены.
- **+** Аддитивно, под kill-switch, per-repo, never-raise, fail-safe → полный цикл; нулевая
регрессия для enduro и orchestrator при выключении.
- **** lite-аналитик эмитит 02/03 заглушки (компромисс ради неизменности гейта); эскалация v1
требует операторского действия (авто-триаж сложности — будущее, ORCH-13/Вариант 3).
- **Откат:** `bug_fast_track_enabled=False` (мгновенно); колонка `tasks.track` аддитивна и
безвредна (дефолт `'full'`).
## Связанные решения
- ORCH-089 (auto-label) — переиспользуемый аппарат label-чтения: [adr-0018](adr-0018-auto-label-gates.md)
- ORCH-088 (serial gate) — композиция очереди репо
- ORCH-027 (coverage-gate) — структурный союзник BR-4: [adr-0029](adr-0029-coverage-gate.md)
- ORCH-090 (cancelled) — паттерн аддитивной колонки `tasks.*`: [adr-0026](adr-0026-stop-cancel-task.md)
## Ссылки
- Детальный ADR задачи: `docs/work-items/ORCH-019/06-adr/ADR-001-bug-fast-track.md`
- BRD/TRZ/AC: `docs/work-items/ORCH-019/01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`
</content>

View File

@@ -106,6 +106,17 @@ claude.exe --print --system-prompt --allowedTools Read,Write,Edit,Bash
Примечание: переход `review → testing` использует `check_reviewer_verdict` (читается из frontmatter `12-review.md`); `development → review``check_tests_local` (оркестратор сам прогоняет тесты, не зависит от Gitea CI).
**Багфикс-трек: routing-override на ребре выхода из `analysis` (ORCH-019 — design).** Для задачи
с `tasks.track='bug'` (помечена в `start_pipeline` по метке Plane `Bug` через аппарат ORCH-089)
`advance_stage` на шаге 3 переопределяет результат `get_next_stage('analysis')`: `next_stage`
`development` (вместо `architecture`), а на шаге 4 `next_agent``developer` (вместо `architect`)
→ стадия `architecture` и её exit-гейт `check_architecture_done` для багфикса не исполняются.
`STAGE_TRANSITIONS`/`get_next_stage`/`get_agent_for_stage` остаются чистыми (1:1) — override живёт
только в `advance_stage`. Чистый предикат `bug_fast_track.skips_architecture(track)` (leaf
`src/bug_fast_track.py`, never-raise) под `bug_fast_track_enabled`; `track` читается из БД, не из
сети (NFR-4). `False`/неприменимый репо → маршрут байт-в-байт прежний. Детали —
[adr-0032](adr/adr-0032-bug-fast-track.md).
### 6. Review Bounce
При REQUEST_CHANGES:

View File

@@ -0,0 +1,7 @@
# Business Request: Режим багфиксинга: упрощённый/дешёвый трек для багов (не полный цикл)
Work Item ID: ORCH-019
## Description
TBD

View File

@@ -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>

View File

@@ -0,0 +1,207 @@
---
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-<slug>.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 условный учёт гейтом.
</content>

View File

@@ -0,0 +1,139 @@
---
work_item: ORCH-019
stage: analysis
author_agent: analyst
status: ready-for-review
created_at: 2026-06-10
model_used: claude-opus-4-8
---
# 03 — Критерии приёмки (Acceptance Criteria): ORCH-019 — Режим багфиксинга
Work Item: **ORCH-019** · Repo: **orchestrator** · Стадия: analysis
Формат: каждый критерий имеет **PASS** (что должно быть истинно для приёмки) и **FAIL** (что
считается провалом). Reviewer/tester проверяют их буквально по файлам репозитория и тестам.
> ⚠️ Корневой инвариант (см. AC-3/AC-8): срезается только аналитика/архитектура; ни один Quality
> Gate не ослаблен. Это главное условие приёмки — нарушение = безусловный FAIL всей задачи.
---
## AC-1 — Классификация задачи по метке `Bug`
**Условие:** issue с меткой Plane `bug_fast_track_label` (дефолт `Bug`) при включённом флаге и
применимом репо распознаётся как багфикс-задача.
- **PASS:** при `bug_fast_track_enabled=True` и `applies(repo)==True` для issue с меткой `Bug`
`is_bug_task(...)` возвращает `True` (через `labels.has_label``plane_sync.fetch_issue_labels`);
задача стартует на багфикс-треке. Источник метки — Plane API, не payload вебхука.
- **FAIL:** метка `Bug` игнорируется; ИЛИ тип читается из payload вебхука; ИЛИ задача без метки
`Bug` ошибочно попадает на багфикс-трек.
---
## AC-2 — Укороченный маршрут: пропуск стадии `architecture`
**Условие:** багфикс-задача проходит конвейер, минуя стадию `architecture`.
- **PASS:** для багфикс-задачи переход из `analysis` ведёт в `development` (а не `architecture`);
стадия `architecture` и её требование `06-adr/` для багфикса не исполняются; задача доходит до
`done`. Маршрут не-баг задачи остаётся `analysis → architecture → development → …`.
- **FAIL:** багфикс-задача всё равно проходит `architecture`; ИЛИ не-баг задача начинает пропускать
`architecture`; ИЛИ `STAGE_TRANSITIONS` изменён структурно (новые/удалённые стадии).
---
## AC-3 — Все Quality Gate'ы исполнены на багфикс-треке (корневой инвариант)
**Условие:** на багфикс-треке исполняются все гейты качества без изменений.
- **PASS:** для багфикс-задачи отрабатывают `check_ci_green`, `check_reviewer_verdict`
(`12-review.md`), `check_tests_passed` (`13-test-report.md`), `check_staging_status`,
`check_deploy_status` и под-гейты ребра `deploy-staging→deploy` (security → merge → coverage →
image-freshness) и merge-verify ребра `deploy→done`. Реестр `QG_CHECKS`, сигнатуры `check_*`,
вердикт-ключи (`verdict:`/`result:`/`deploy_status:`/`staging_status:`/`security_status:`/
`coverage_status:`) и порядок под-гейтов — байт-в-байт прежние.
- **FAIL:** хоть один гейт качества пропущен/ослаблен/изменён на багфикс-треке; ИЛИ изменён состав
`QG_CHECKS` / имя или регистр любого вердикт-ключа / порядок под-гейтов.
---
## AC-4 — Обязательный регресс-тест
**Условие:** багфикс фиксирует дефект тестом.
- **PASS:** PR багфикса содержит новый/изменённый тест, воспроизводящий исправляемый дефект
(красный на коде до фикса, зелёный после); требование закреплено в `04-test-plan.yaml` багфикса
и в reviewer-оси (`.openclaw/agents/reviewer.md`: фикс без теста → finding ≥P1 / REQUEST_CHANGES).
- **FAIL:** багфикс мержится без теста-фиксатора; ИЛИ reviewer-ось отсутствует/не срабатывает; ИЛИ
тест присутствует, но не падает на исходном (нефиксированном) коде.
---
## AC-5 — Эскалация сложного бага в полный цикл
**Условие:** сложный/архитектурный/визуальный баг возвращается в полный цикл.
- **PASS:** существует и документирован путь эскалации (минимум ручной: снятие метки `Bug` /
перевод стадии, и/или решение мини-аналитика «баг сложный → не фаст-трекать»); после эскалации
задача проходит штатный маршрут с `architecture`.
- **FAIL:** механизма эскалации нет; ИЛИ багфикс-задача необратимо застревает без `architecture`,
когда баг требует архитектурного решения/макета.
---
## AC-6 — Fail-safe → полный цикл (нулевая регрессия)
**Условие:** при выключении/ошибке/неприменимости — строго прежнее поведение (полный цикл).
- **PASS:** при `bug_fast_track_enabled=False`, неприменимом репо, ошибке/таймауте/неоднозначности
чтения метки, отсутствии метки `Bug` — задача стартует на `analysis` и идёт маршрутом с
`architecture` (как до ORCH-019). Логика never-raise: ошибка не роняет `start_pipeline`/вебхук.
При выключенном флаге путь старта и маршрут идентичны текущим (диффом по поведению — нулевые).
- **FAIL:** ошибка/неоднозначность приводит к молчаливому пропуску стадий; ИЛИ исключение из
логики классификации роняет вебхук/конвейер; ИЛИ при выключенном флаге поведение отличается от
прежнего.
---
## AC-7 — Наблюдаемость трека и метрика стоимости
**Условие:** факт багфикс-трека и экономия наблюдаемы.
- **PASS:** `GET /queue` содержит аддитивный read-only блок `bug_fast_track` (флаг/область/метка +
счётчик задач на треке + агрегатная метрика экономии стадий/agent-runs/токенов/времени);
решение о маршруте логируется; существующие ключи `GET /queue` не изменены.
- **FAIL:** трек/метрика ненаблюдаемы; ИЛИ блок ломает существующий контракт `GET /queue`; ИЛИ
ошибка построения блока роняет эндпоинт (нарушен never-raise).
---
## AC-8 — Аддитивность и self-hosting безопасность
**Условие:** изменение аддитивно и безопасно для общего прод-инстанса.
- **PASS:** миграции БД (если есть) аддитивны и идемпотентны (`_ensure_column`/`CREATE TABLE IF NOT
EXISTS`); enduro при выключенном/неприменимом флаге не затронут; механизм не рестартит/не роняет
прод-контейнер, не пушит/force-push в `main`. Полный регресс `tests/` зелёный.
- **FAIL:** ломающая миграция/изменение существующих контрактов; ИЛИ затронут enduro при выключенном
флаге; ИЛИ механизм трогает прод-контейнер/`main`; ИЛИ красный `tests/`.
---
## AC-9 — Композиция с существующими гейтами
**Условие:** багфикс-трек корректно сосуществует с ORCH-088/089/027/043.
- **PASS:** багфикс-задача корректно учитывается serial-gate (ORCH-088) как обычная задача репо;
`autoApprove`/`autoDeploy` (ORCH-089) работают на багфикс-треке; coverage-gate (ORCH-027) и
merge-gate (ORCH-043) исполняются штатно. Интеграционный тест композиции зелёный.
- **FAIL:** изменённая точка входа ломает serial-очередь/auto-label/merge/coverage; ИЛИ багфикс-
задача обходит serial-gate.
---
## Сводная матрица AC ↔ BR/FR
| AC | Покрывает |
|----|-----------|
| AC-1 | BR-1 / FR-1 |
| AC-2 | BR-2 / FR-2 |
| AC-3 | BR-3 / FR-3 / NFR-1 |
| AC-4 | BR-4 / FR-4 |
| AC-5 | BR-5 / FR-5 |
| AC-6 | BR-6 / FR-6 / NFR-2 / NFR-3 |
| AC-7 | BR-7 / FR-7 |
| AC-8 | BR-8 / NFR-2 / NFR-6 |
| AC-9 | NFR-7 |
</content>

View File

@@ -0,0 +1,111 @@
work_item: ORCH-019
stage: analysis
author_agent: analyst
status: ready-for-review
created_at: 2026-06-10
model_used: claude-opus-4-8
title: "Багфикс-трек: классификация по метке, укороченный маршрут, сохранность гейтов, fail-safe"
framework: pytest
scope: >
Покрывает: классификацию задачи как бага по метке Plane (ORCH-089-аппарат), маршрутизацию
багфикса в обход стадии architecture, сохранность ВСЕХ Quality Gate'ов, обязательность
регресс-теста, эскалацию в полный цикл, fail-safe → полный цикл, наблюдаемость/метрику,
аддитивность и композицию с serial-gate/auto-label/coverage. Вне покрытия: реальный
Plane/Gitea I/O (мокается), роутинг моделей ORCH-13, LLM-авто-триаж сложности.
notes: >
Сетевые вызовы Plane (fetch_issue_labels/get_project_labels) мокаются. Полный регресс tests/
должен оставаться зелёным. Тесты на сохранность гейтов проверяют НЕИЗМЕННОСТЬ QG_CHECKS/check_*/
вердикт-ключей — это анти-регресс корневого инварианта (NFR-1). Финальные имена модулей/функций
(labels.py vs новый bug_fast_track.py; tasks.track колонка) фиксирует архитектор — TC привязаны
к поведению, имена путей уточняются на стадии разработки.
tests:
- id: TC-01
type: unit
description: "is_bug_task() возвращает True для issue с меткой 'Bug' (has_label True); метка читается из Plane API, не из payload."
module: tests/test_bug_fast_track.py
expected: PASS
- id: TC-02
type: unit
description: "is_bug_task() возвращает False при отсутствии метки, неоднозначной метке или labels=None (fail-safe)."
module: tests/test_bug_fast_track.py
expected: PASS
- id: TC-03
type: unit
description: "bug_fast_track_applies(repo): первым проверяется локальная область (enabled + CSV repos) до любого сетевого вызова; выключенный флаг → False без обращения к has_label."
module: tests/test_bug_fast_track.py
expected: PASS
- id: TC-04
type: unit
description: "never-raise: исключение в fetch_issue_labels/get_project_labels не пробрасывается — is_bug_task деградирует в False (полный цикл)."
module: tests/test_bug_fast_track.py
expected: PASS
- id: TC-05
type: unit
description: "Маршрут багфикса: для bug-задачи следующая стадия после analysis = development (architecture пропущена); для не-баг задачи = architecture."
module: tests/test_bug_fast_track_routing.py
expected: PASS
- id: TC-06
type: unit
description: "STAGE_TRANSITIONS структурно не изменён: набор стадий и рёбер байт-в-байт прежний (анти-регресс)."
module: tests/test_bug_fast_track_routing.py
expected: PASS
- id: TC-07
type: unit
description: "Реестр QG_CHECKS и сигнатуры check_* не изменены багфикс-треком; вердикт-ключи (verdict/result/deploy_status/staging_status/security_status/coverage_status) сохранены по имени и регистру."
module: tests/test_bug_fast_track_gates.py
expected: PASS
- id: TC-08
type: integration
description: "E2E багфикс-трек: bug-задача проходит development→review→testing→deploy-staging→deploy с исполнением всех гейтов (check_ci_green/reviewer_verdict/tests_passed/staging/deploy + под-гейты security/merge/coverage/image-freshness), минуя architecture."
module: tests/test_bug_fast_track_e2e.py
expected: PASS
- id: TC-09
type: integration
description: "start_pipeline: issue с меткой Bug (флаг вкл, репо применим) создаёт задачу на багфикс-треке; issue без метки — на полном цикле (точка входа analysis + маршрут с architecture)."
module: tests/test_bug_fast_track_e2e.py
expected: PASS
- id: TC-10
type: integration
description: "Fail-safe: при bug_fast_track_enabled=False путь старта и маршрут идентичны прежним (нулевая регрессия) — задача с меткой Bug идёт полным циклом."
module: tests/test_bug_fast_track_e2e.py
expected: PASS
- id: TC-11
type: integration
description: "Эскалация: после снятия метки Bug / решения 'баг сложный' задача проходит штатный маршрут с architecture (возврат в полный цикл)."
module: tests/test_bug_fast_track_escalation.py
expected: PASS
- id: TC-12
type: unit
description: "check_analysis_approved/check_analysis_complete не блокирует ложно облегчённый багфикс-пакет, но сохраняет прежнюю проверку для не-баг задач (требование FR-6)."
module: tests/test_bug_fast_track_gates.py
expected: PASS
- id: TC-13
type: integration
description: "GET /queue содержит аддитивный read-only блок bug_fast_track (enabled/repos/label/счётчик/метрика); существующие ключи неизменны; ошибка построения блока не роняет эндпоинт."
module: tests/test_queue_endpoint.py
expected: PASS
- id: TC-14
type: integration
description: "Композиция: багфикс-задача учитывается serial-gate (ORCH-088) как обычная задача репо и не обходит его; autoApprove/autoDeploy (ORCH-089) применимы на багфикс-треке."
module: tests/test_bug_fast_track_composition.py
expected: PASS
- id: TC-15
type: unit
description: "Миграция (если введена колонка tasks.track) аддитивна и идемпотентна: повторный init_db/_ensure_column не падает; дефолт 'full' для существующих строк."
module: tests/test_db_migrations.py
expected: PASS

View File

@@ -0,0 +1,231 @@
---
work_item: ORCH-019
stage: architecture
author_agent: architect
status: proposed
created_at: 2026-06-10
model_used: claude-opus-4-8
---
# ADR-001: Багфикс-трек — пропуск стадии `architecture` через track-aware routing override
Work Item: **ORCH-019** — упрощённый/дешёвый трек для багов (укороченный маршрут конвейера)
Стадия: **architecture**
Сквозная регистрация: **`docs/architecture/adr/adr-0032-bug-fast-track.md`** (решение
кросс-каттинговое: новый leaf-компонент + аддитивная колонка `tasks.track` + семантика
маршрутизации, затрагивающая `advance_stage`).
## Статус
Proposed
## Контекст
Любая задача входит в конвейер через `webhooks/plane.py::start_pipeline`, который
**жёстко** создаёт task-row со стадией `"analysis"` (`create_task_atomic(..., "analysis", ...)`)
и режет ветку. Маршрут стадий полностью управляется `src/stages.py::STAGE_TRANSITIONS` через
`get_next_stage``advance_stage` (`src/stage_engine.py`) НЕ зашивает порядок, а спрашивает
`get_next_stage(current_stage)` (строка 214) и `get_agent_for_stage(current_stage)` (строка 464).
Для мелкого бага полный цикл `analysis → architecture → development → …` избыточен: стадия
`architecture` = отдельный прогон агента `architect` (opus, дорогой) + ADR + exit-гейт
`check_architecture_done`. Прецедент: UI z-index баг ET-9/ET-014 прошёл полный цикл ~35 мин.
**Корневой инвариант (NFR-1 BRD, нерушимый):** упрощаем только *аналитику/архитектуру*; ни один
Quality Gate / exit-код deploy-хука / под-гейт (security/merge/coverage/image-freshness) — НЕ
ослаблен. Горький урок ET-8: срезанная *проверка* = недоделка на проде.
**Факты, сверенные с кодом:**
- `src/labels.py::has_label` + `plane_sync.fetch_issue_labels`/`get_project_labels` (ORCH-089) —
готовый, проверенный аппарат чтения метки Plane (TTL-кэш, нормализация, never-raise,
fail-safe → False, источник истины Plane API, не payload).
- `advance_stage` маршрутизирует через `get_next_stage`/`get_agent_for_stage` → точка ветвления
локализуема, `STAGE_TRANSITIONS` ломать не нужно.
- `check_analysis_approved` (exit-гейт `analysis`) вызывает `check_analysis_complete`, требующий
**01/02/03/04** (`src/qg/checks.py:33`). Это и есть точка риска ложной блокировки облегчённого
пакета (FR-6).
- `_ensure_column` (`src/db.py:334`) — идемпотентная аддитивная миграция (паттерн
`tasks.cancelled_at`, ORCH-090).
## Решение
### Сводка
Багфикс-трек — **свойство планировщика/точки входа, не Quality Gate**. Задача с меткой Plane
`Bug` помечается в БД как `track='bug'`; на ребре выхода из `analysis` `advance_stage` применяет
**чистый routing-override**: `next_stage``development` (вместо `architecture`), `next_agent`
`developer` (вместо `architect`). `STAGE_TRANSITIONS`, реестр `QG_CHECKS`, все `check_*` и
вердикт-ключи — **байт-в-байт прежние**. Распознавание, маршрут и метрика — аддитивно, под
kill-switch, с областью репо, never-raise, fail-safe → полный цикл.
### D1 — Классификация: метка Plane `Bug`, читаемая в `start_pipeline` (FR-1, AC-1)
Новый leaf `src/bug_fast_track.py` (пустой импорт-граф как `serial_gate`/`labels`: только
`config`, лениво `labels`/`plane_sync`/`qg.checks`), never-raise. Публичные функции:
- `bug_fast_track_applies(repo) -> bool` — локальный, без сети, по образцу `_auto_label_applies`:
`bug_fast_track_enabled=False``False`; `bug_fast_track_repos` (CSV) непустой → только
перечисленные репо; **пусто → self-hosting only** (`is_self_hosting_repo`, см. D6). Проверяется
**ПЕРВЫМ** → при выключенном флаге нулевой сетевой оверхед, enduro не затронут.
- `is_bug_task(work_item_id, project_id) -> bool``bug_fast_track_applies` уже проверен
вызывающим; делегирует в `labels.has_label(work_item_id, settings.bug_fast_track_label,
project_id)` (дефолт метки `Bug`). Любая ошибка/неоднозначность → `False` (fail-safe → полный
цикл).
Чтение метки — **только** в `start_pipeline` (момент старта, сетевой вызов приемлем, как
ORCH-089), **никогда** в горячем `claim_next_job` (NFR-4).
### D2 — Хранение типа: аддитивная колонка `tasks.track` (OQ-2, NFR-4)
Идемпотентная миграция `_ensure_column(conn, "tasks", "track", "TEXT DEFAULT 'full'")` рядом с
`tasks.cancelled_at`/`cancel_requested_at` (`src/db.py` init). Значения: `'full'` (дефолт, ВСЕ
существующие и не-баг задачи) | `'bug'`. Хелперы: `db.set_task_track(task_id, track)` (запись),
`db.get_task_track(task_id) -> str` (чтение, дефолт `'full'`). Тип читается из **БД** в
`advance_stage` (NFR-4: горячий путь без сети). Альтернатива «выводить тип повторным чтением
метки» отвергнута — повторный сетевой вызов в горячем пути запрещён.
`create_task_atomic` НЕ меняет сигнатуру: задача создаётся как `'full'` (DEFAULT), затем
`start_pipeline` после успешного `created=True` при `is_bug_task` вызывает
`db.set_task_track(task_id, 'bug')`. Точка входа стадии остаётся `"analysis"` (мини-анализ
сохраняется, OQ-3/BRD §6 — НЕ чистый hotfix).
### D3 — Routing-override: пропуск `architecture` без правки `STAGE_TRANSITIONS` (FR-2, AC-2)
`get_next_stage`/`get_agent_for_stage` остаются **чистыми** (принимают только стадию, 1:1).
Override живёт в `advance_stage`, сразу после строки `next_stage = get_next_stage(current_stage)`:
```python
next_stage = get_next_stage(current_stage)
# ORCH-019: bug-fast-track skips the architecture stage entirely.
if current_stage == "analysis" and bug_fast_track.skips_architecture(track):
next_stage = "development"
```
и при запуске следующего агента (строка 464):
```python
next_agent = get_agent_for_stage(current_stage) # "analysis" -> "architect"
if current_stage == "analysis" and next_stage == "development":
next_agent = "developer" # skip architect run
```
`track` читается один раз в начале `advance_stage` (`db.get_task_track(task_id)`). Чистый
предикат `bug_fast_track.skips_architecture(track) -> bool` (== `track == 'bug'` под
`bug_fast_track_enabled`; иначе `False`). Багфикс-задача физически НЕ попадает в стадию
`architecture` → её exit-гейт `check_architecture_done` и требование `06-adr/` не исполняются для
багфикса. Для не-баг задач (`track='full'`) поведение **байт-в-байт** прежнее.
**Сопутствующая правка телеметрии:** строка 386 стампит `mark_brd_review_ended` при
`analysis → architecture`. Для багфикса next_stage = `development`, поэтому условие расширяется до
`current_stage == "analysis" and next_stage in ("architecture", "development")` — чтобы метрика
«твоё время» (ORCH-087) оставалась честной на багфикс-треке. Не влияет на гейты.
### D4 — Quality Gate `analysis`: НЕ трогаем; lite-пакет эмитит все 4 файла (FR-3/FR-6, OQ-6, AC-3)
**Корневой инвариант диктует минимальную поверхность изменения гейтов = ноль.**
`check_analysis_complete` (требует 01/02/03/04) и `check_analysis_approved` остаются **байт-в-байт
прежними**. Багфикс-аналитик (`analyst.md` lite-режим) всё равно эмитит **все 4** файла, но в
облегчённой багфикс-форме: `01-brd.md` = короткий bug-report (симптом / шаги воспроизведения /
локализация / причина), `02-trz.md` + `03-acceptance-criteria.md` = краткие bug-shaped заглушки,
`04-test-plan.yaml` = план **обязательного регресс-теста** (красный до фикса, зелёный после).
Обоснование выбора: доминирующая экономия — пропуск **всей стадии `architecture`** (отдельный
прогон opus-агента `architect` + ADR), а не число файлов analysis (они эмитятся в ОДНОМ прогоне
analyst-агента). Сохранение 4-файлового гейта = **сильнейшая** позиция NFR-1 (нулевая поверхность
правок гейта) ценой почти нулевого оверхеда. Альтернатива «track-aware `check_analysis_complete`
(для bug требовать только 01/04)» рассмотрена и отвергнута для v1 (D-Alt) — она трогает `check_*`
и расширяет поверхность риска без существенной экономии.
### D5 — Эскалация в полный цикл (FR-5, AC-5)
Два пути возврата сложного/архитектурного/визуального бага в полный цикл, оба сбрасывают
`track='bug'``'full'` (после чего `advance_stage` маршрутизирует `analysis → architecture`
штатно):
1. **Операторский (ручной, v1-дефолт):** админ-эндпоинт `POST /bug-fast-track/escalate?work_item=<id>`
(по образцу `POST /serial-gate/unfreeze`, `POST /coverage/baseline`) — `db.set_task_track(...,
'full')`, лог + Telegram + Plane-коммент, never-raise. Применять, пока задача в `analysis`
(до выхода) — тогда следующий переход уйдёт в `architecture`.
2. **Решение мини-аналитика:** если на багфикс-треке аналитик определяет, что баг архитектурный,
он эмитит **полный** analysis-пакет (включая запрос на `06-adr/`) и помечает в bug-report
`escalate: full-cycle` — оператор подтверждает эскалацию эндпоинтом (1). v1 НЕ включает
автоматический LLM-авто-триаж сложности (вне объёма, BRD §2.2).
Эскалация обратима, детерминирована, наблюдаема. Багфикс-задача не «застревает» без архитектуры.
### D6 — Область по умолчанию: self-hosting only (OQ-5, NFR-5)
Пустой `bug_fast_track_repos`**self-hosting only** (`is_self_hosting_repo`, как
ORCH-089/027/058). Это безопасный дефолт: режим обкатывается на самом орке (где метка `Bug`
гарантированно заводится оператором), enduro подключается явным добавлением в CSV. Флаги
(`config.py`): `bug_fast_track_enabled` (kill-switch, env `ORCH_BUG_FAST_TRACK_ENABLED`),
`bug_fast_track_label` (дефолт `Bug`, env `ORCH_BUG_FAST_TRACK_LABEL`), `bug_fast_track_repos`
(CSV, env `ORCH_BUG_FAST_TRACK_REPOS`).
### D7 — Наблюдаемость стоимости (FR-7, AC-7)
- **`GET /queue`** — аддитивный read-only блок `bug_fast_track` (`bug_fast_track.snapshot()`,
never-raise, по образцу `serial_gate`/`auto_labels`/`coverage`): `enabled`, `repos`, `label`,
счётчик задач с `track='bug'`, агрегатная метрика экономии (пропущенные стадии / Σ agent-runs /
токены / время багфикс-трека против среднего полного цикла из существующей телеметрии
`agent_runs`). Существующие ключи `GET /queue` не меняются.
- **Лог-строка** на решение о маршруте (`analysis → development (bug-fast-track)`).
- **Опц.** отметка `🐞 багфикс-трек` в Telegram-карточке (`notifications.py`, never-raise).
### D8 — Композиция (NFR-7, AC-9)
- **serial-gate (ORCH-088):** багфикс-задача — обычная задача репо, учитывается в serial-очереди
как есть (FIFO `t2.id < jobs.task_id`); точка входа `analysis` не меняется, defer-branch логика
не затронута. Маркированный код `serial_gate.py` НЕ правится.
- **auto-label (ORCH-089):** `autoApprove`/`autoDeploy` работают на багфикс-треке — autoApprove
врезка в `_handle_analysis_approved_flow` вызывает `advance_stage(finished_agent=None)`, который
применяет D3-override и уходит в `development`. Переиспользуем `labels.has_label`.
- **coverage-gate (ORCH-027):** союзник BR-4 (структурно ловит «код без теста») — исполняется
штатно на ребре `deploy-staging → deploy`.
- **merge-gate (ORCH-043):** не затронут.
Правки маркированного кода (`advance_stage` несёт врезки ORCH-088/089/027/059/094) — точечные,
со сверкой их `06-adr/`; зафиксированные инварианты (порядок под-гейтов, merge-lease,
terminal-sync) НЕ нарушаются: ORCH-019 добавляет ветвление ТОЛЬКО на ребре выхода из `analysis`,
до всех deploy-edge под-гейтов.
## Альтернативы
- **Track-aware `get_next_stage(stage, task)` / новая стадия в `STAGE_TRANSITIONS`** — отвергнуто:
ломает чистоту `stages.py` и риск задеть структуру таблицы (AC-2 FAIL при структурном изменении).
Override в `advance_stage` локальнее и держит `STAGE_TRANSITIONS` неизменным.
- **Track-aware `check_analysis_complete` (bug → только 01/04)** — отвергнуто для v1 (D-Alt):
трогает `check_*`, расширяет поверхность риска NFR-1 ради почти нулевой экономии (см. D4).
Оставлено как возможное будущее уточнение, если потребуется реальный отказ от 02/03.
- **Чистый hotfix `start_pipeline → development`, минуя `analysis`** — отвергнуто как дефолт
(BRD §6): теряется фиксация регресс-теста как контракта приёмки и трассируемость (урок ET-8).
- **Тип задачи из payload вебхука / повторное чтение метки в `claim_next_job`** — отвергнуто:
payload не несёт `type` (источник истины — Plane API); сеть в горячем claim запрещена (NFR-4).
- **Чтение типа без БД-колонки** — отвергнуто: потребовало бы сетевого вызова в горячем пути.
## Последствия
- **+** Багфикс минует целую стадию `architecture` (один прогон opus-агента `architect` + ADR) —
основная экономия токенов/времени; гейты качества **байт-в-байт** сохранены.
- **+** Полностью аддитивно: kill-switch `False` или неприменимый репо → путь старта и маршрут
идентичны текущим (AC-6, нулевая регрессия для enduro и orchestrator).
- **+** Переиспользует проверенный аппарат ORCH-089 (label-чтение) и паттерн leaf+флаги+snapshot.
- **** Багфикс-аналитик всё равно эмитит 02/03 (краткие заглушки) ради неизменности гейта —
принятый компромисс (D4); экономия на их содержании, не на их наличии.
- **** Эскалация v1 требует операторского действия (эндпоинт) — авто-триаж сложности отложен
(BRD §2.2). Митигатор: путь эскалации документирован, обратим, наблюдаем (D5).
- **Откат:** `bug_fast_track_enabled=False` (мгновенно, 1:1 прежнее поведение); колонка
`tasks.track` остаётся (аддитивна, дефолт `'full'`, безвредна). Полный откат — revert PR;
миграция идемпотентна, остаточная колонка не мешает.
## Ссылки
- BRD: `docs/work-items/ORCH-019/01-brd.md`
- TRZ: `docs/work-items/ORCH-019/02-trz.md`
- Acceptance: `docs/work-items/ORCH-019/03-acceptance-criteria.md`
- Сквозной ADR: `docs/architecture/adr/adr-0032-bug-fast-track.md`
- Data: `docs/work-items/ORCH-019/08-data-requirements.md`
- Infra: `docs/work-items/ORCH-019/07-infra-requirements.md`
- Риски: `docs/work-items/ORCH-019/10-tech-risks.md`
- Сверено по коду: `src/stages.py`, `src/stage_engine.py` (advance_stage:175-477),
`src/webhooks/plane.py::start_pipeline` (505-684), `src/labels.py`,
`src/qg/checks.py` (check_analysis_complete:33, check_analysis_approved:286,
check_architecture_done:62), `src/db.py` (_ensure_column:334, create_task_atomic:433)
</content>
</invoke>

View File

@@ -0,0 +1,62 @@
---
work_item: ORCH-019
stage: architecture
author_agent: architect
status: proposed
created_at: 2026-06-10
model_used: claude-opus-4-8
---
# 07 — Инфраструктурные требования (Infra Requirements): ORCH-019 — Багфикс-трек
Work Item: **ORCH-019** · Repo: **orchestrator** · Стадия: architecture
> **Топология не меняется.** Один прод-контейнер `orchestrator` (8500) + staging (8501) на mva154,
> общая SQLite-БД. ORCH-019 — чисто прикладное изменение под флагом. Этот документ фиксирует
> **предусловия включения** (Plane-метка + env-флаги), не новую инфраструктуру.
---
## 1. Предусловие: метка `Bug` в Plane-проекте (блокирующее для активации)
Багфикс-трек активируется по метке Plane с именем `bug_fast_track_label` (дефолт `Bug`),
читаемой аппаратом ORCH-089 (`fetch_issue_labels`/`get_project_labels`). **Метка должна
существовать** в Plane-проекте orchestrator (и в любом проекте, добавленном в
`bug_fast_track_repos`).
- Её **отсутствие = fail-safe полный цикл** (`has_label → False`), не сбой. Включение флага без
заведённой метки безопасно, но эффекта не даёт.
- Создаётся оператором в Plane вручную (как `autoApprove`/`autoDeploy` для ORCH-089).
## 2. Конфигурация (env-флаги, `src/config.py`)
| Флаг | Env | Дефолт | Назначение |
|------|-----|--------|-----------|
| `bug_fast_track_enabled` | `ORCH_BUG_FAST_TRACK_ENABLED` | `False` | kill-switch; `False` → путь старта/маршрут строго прежние (нулевая регрессия) |
| `bug_fast_track_label` | `ORCH_BUG_FAST_TRACK_LABEL` | `Bug` | имя метки Plane для распознавания бага |
| `bug_fast_track_repos` | `ORCH_BUG_FAST_TRACK_REPOS` | `""` (пусто) | CSV-область; пусто → **self-hosting only** (`orchestrator`) |
> Рекомендация выката: `enabled=False` до момента, когда метка `Bug` заведена в Plane и проведён
> staging-прогон. Дефолт области (пустой CSV) = self-hosting only → enduro не затронут даже при
> включённом флаге.
## 3. Зависимости / образ
- **Новых pip-зависимостей нет.** Переиспользуются существующие `httpx`/`plane_sync` (label-чтение)
и `sqlite3` (колонка `tasks.track`). Пересборка образа из-за зависимостей не требуется.
- **Миграция БД** (`tasks.track`) применяется идемпотентно при старте приложения (`_ensure_column`)
— без ручного шага, без даунтайма (ALTER ADD COLUMN на SQLite — мгновенный).
## 4. Self-hosting безопасность (NFR-6)
- Механизм **не** рестартит/не роняет прод-контейнер, **не** пушит/force-push в `main`. Это
routing-решение планировщика + аддитивная колонка + read-only наблюдаемость.
- Выкат самого ORCH-019 на прод орка идёт штатным конвейером через обязательный
`deploy-staging` (8501) → `Confirm Deploy` (ORCH-059). Топология/процедура — `docs/operations/INFRA.md`.
## 5. Новый эндпоинт (эскалация)
`POST /bug-fast-track/escalate?work_item=<id>` — админ-ручка возврата задачи в полный цикл
(`track → 'full'`), по образцу `POST /serial-gate/unfreeze`. Без новой инфраструктуры (тот же
FastAPI-приложение/порт). Read-only блок `bug_fast_track` добавляется в существующий `GET /queue`.
</content>

View File

@@ -0,0 +1,64 @@
---
work_item: ORCH-019
stage: architecture
author_agent: architect
status: proposed
created_at: 2026-06-10
model_used: claude-opus-4-8
---
# 08 — Требования к данным (Data Requirements): ORCH-019 — Багфикс-трек
Work Item: **ORCH-019** · Repo: **orchestrator** · Стадия: architecture
> ⚠️ Общая прод-БД (self-hosting + enduro). Только **аддитивные, идемпотентные** миграции;
> существующие контракты таблиц не меняются.
---
## 1. Новая колонка `tasks.track`
| Атрибут | Значение |
|---------|----------|
| Таблица | `tasks` |
| Колонка | `track` |
| Тип | `TEXT` |
| DEFAULT | `'full'` |
| Допустимые значения | `'full'` (дефолт; ВСЕ существующие и не-баг задачи) \| `'bug'` |
| Миграция | `_ensure_column(conn, "tasks", "track", "TEXT DEFAULT 'full'")` (идемпотентно, паттерн `tasks.cancelled_at` ORCH-090) |
| Размещение | рядом с `_ensure_column(conn, "tasks", "cancel_requested_at", ...)` в init `src/db.py` |
**Семантика:** тип задачи (полный цикл / багфикс). Записывается в `start_pipeline` после
успешного `create_task_atomic` (`created=True`) при `is_bug_task==True`. Читается в `advance_stage`
для routing-override (D3) — из БД, **никогда** из сети (NFR-4).
## 2. Хелперы доступа (`src/db.py`)
| Хелпер | Контракт |
|--------|----------|
| `set_task_track(task_id: int, track: str) -> None` | `UPDATE tasks SET track=? WHERE id=?`; идемпотентно; never-raise на уровне вызова в `start_pipeline`/escalate |
| `get_task_track(task_id: int) -> str` | `SELECT track FROM tasks WHERE id=?`; отсутствие/NULL → `'full'` (fail-safe → полный цикл) |
## 3. Что НЕ меняется
- Сигнатура `create_task_atomic(plane_id, work_item_id, repo, branch, stage, title)`
**без изменений** (задача создаётся как `track='full'` по DEFAULT, тип проставляется отдельным
`set_task_track`).
- Существующие колонки `tasks` (прочие), таблицы `jobs`, `job_deps`, `agent_runs`,
`coverage_baseline`, `repo_freeze`, `tracker_messages`**без изменений**.
- `claim_next_job`**без изменений** (не читает `track`; сеть/маршрут в горячем claim не вводятся).
## 4. Обратная совместимость / откат
- Колонка аддитивна с безопасным DEFAULT `'full'` → существующие строки и enduro-задачи ведут
себя как сегодня без обратной записи.
- Откат фичи (`bug_fast_track_enabled=False`) не требует удаления колонки: при выключенном флаге
`track` не влияет на маршрут (`skips_architecture``False`). Остаточная колонка безвредна.
- Полный revert PR: миграция `_ensure_column` идемпотентна; повторный запуск на БД с уже
существующей колонкой — no-op.
## 5. Объём данных / производительность
- Одна `TEXT`-колонка на строку `tasks` (низкая кардинальность: 2 значения). Индекс не требуется
(чтение по `id` PK в `advance_stage`; агрегат для `GET /queue` — редкий read-only скан).
</content>

View File

@@ -0,0 +1,39 @@
---
work_item: ORCH-019
stage: architecture
author_agent: architect
status: proposed
created_at: 2026-06-10
model_used: claude-opus-4-8
---
# 10 — Технические риски: ORCH-019 — Багфикс-трек
Work Item: **ORCH-019** · Repo: **orchestrator** · Стадия: architecture
> Шкала: вероятность × влияние ∈ {Низк., Средн., Выс.}. Каждый риск — с митигатором, привязанным
> к ADR-001 / AC.
---
| ID | Риск | Вер. | Влияние | Митигатор |
|----|------|------|---------|-----------|
| R-1 | **Срезали лишнее** — ошибочный пропуск гейта качества → недоделка на проде (урок ET-8). | Низк. | Выс. | NFR-1 диктует **нулевую** поверхность правок гейтов (D4): `STAGE_TRANSITIONS`/`QG_CHECKS`/все `check_*`/вердикт-ключи — байт-в-байт; режется ТОЛЬКО стадия `architecture`. Тест AC-3: на багфикс-треке отрабатывают все гейты. |
| R-2 | **Сложный баг под меткой `Bug`** уходит на фаст-трек и упирается в отсутствие архитектуры. | Средн. | Средн. | Эскалация D5 (эндпоинт `escalate` + self-escalate мини-аналитика) сбрасывает `track→full` → задача идёт через `architecture`. AC-5. |
| R-3 | **Регресс-тест не написан** (developer «забыл») → рецидив бага. | Средн. | Выс. | BR-4: обязательный TC в `04-test-plan.yaml` + reviewer-ось (фикс без теста → REQUEST_CHANGES) + структурный союзник coverage-gate ORCH-027. AC-4. |
| R-4 | **Fail-safe инвертирован** — ошибка чтения метки молча срежет стадии. | Низк. | Выс. | never-raise leaf `bug_fast_track.py`: любая ошибка/неоднозначность/`None`-labels → `is_bug_task=False` → полный цикл; `get_task_track` при NULL → `'full'`. AC-6. |
| R-5 | **Конфликт с serial-gate/auto-label** при изменённой точке входа. | Низк. | Средн. | Точка входа НЕ меняется (задача стартует на `analysis`, ветвление — только на ребре выхода). serial_gate/auto-label маркированный код не правится. Интеграционный тест композиции (AC-9). |
| R-6 | **Ложная блокировка** облегчённого пакета exit-гейтом `analysis` (`check_analysis_complete` требует 01/02/03/04). | Низк. | Средн. | D4: гейт НЕ трогаем; lite-аналитик эмитит все 4 файла (02/03 — краткие заглушки). FR-6/OQ-6. |
| R-7 | **Правка маркированного `advance_stage`** (несёт врезки ORCH-088/089/027/059/094) сломает чужой инвариант. | Низк. | Выс. | Врезка ORCH-019 — ТОЛЬКО на ребре выхода из `analysis`, ДО всех deploy-edge под-гейтов; порядок под-гейтов/merge-lease/terminal-sync не затронуты (CLAUDE.md §9: сверка `06-adr/` затронутых ORCH-NNN). |
| R-8 | **Телеметрия `mark_brd_review_ended`** не сработает на багфиксе (next=`development`, не `architecture`) → искажённая метрика «твоё время». | Низк. | Низк. | D3: условие расширено до `next_stage in ("architecture","development")`. Не влияет на гейты. |
| R-9 | **Метрика экономии** (FR-7) вводит в заблуждение (несравнимые задачи). | Низк. | Низк. | Метрика помечена как относительная оценка из существующей телеметрии `agent_runs`; без новой тяжёлой инфраструктуры; read-only, never-raise. AC-7. |
---
## Сводный вывод
Доминирующий риск — **R-1 (срезали лишнее)**; он структурно закрыт нулевой поверхностью правок
гейтов (D4) — изменение касается планировщика/точки входа, а не Quality Gate. Остальные риски
покрыты паттерном leaf+флаги+fail-safe (ORCH-088/089/027) и обратимой эскалацией (D5). Откат —
мгновенный через `bug_fast_track_enabled=False`.
</content>

View File

@@ -0,0 +1,108 @@
---
verdict: APPROVED
work_item: ORCH-019
stage: review
author_agent: reviewer
status: approved
created_at: 2026-06-10
model_used: claude-opus-4-8
type: review
work_item_id: ORCH-019
version: 1
---
# Review ORCH-019 — Багфикс-трек (упрощённый/дешёвый маршрут для багов)
## Summary
Реализация соответствует ТЗ (`02-trz.md`), ADR-001 и всем 9 критериям приёмки
(`03-acceptance-criteria.md`). Корневой инвариант NFR-1 («срезается только аналитика/архитектура;
ни один Quality Gate не тронут») соблюдён **структурно**: `src/stages.py` и `src/qg/checks.py`
**пустой diff**; маршрутизация багфикса реализована чистым routing-override в `advance_stage`, как
и предписывал ADR (D3). Полный регресс `tests/` зелёный (**1551 passed**), 46 целевых тестов
ORCH-019 (6 suites) — PASS. Документация обновлена исчерпывающе во всех требуемых поверхностях.
Findings уровня P0/P1 — нет. → **APPROVED**.
## Проверка по осям
### 1. Соответствие ТЗ / Acceptance Criteria
- **AC-1 (классификация по метке `Bug`)** ✓ — `bug_fast_track.is_bug_task` делегирует в
`labels.has_label` (источник истины — Plane API, не payload); `applies(repo)` (локальный)
проверяется ПЕРВЫМ в `start_pipeline` → при выключенном флаге нулевой сетевой оверхед.
- **AC-2 (пропуск `architecture`)** ✓ — override на ребре выхода из `analysis`
(`next_stage → development`, `next_agent → developer`); `STAGE_TRANSITIONS`/`get_next_stage`/
`get_agent_for_stage` остались чистыми (1:1). Анти-регресс структуры — TC-06.
- **AC-3 (все QG сохранены — корневой инвариант)** ✓ — `git diff` по `src/stages.py`/`src/qg/`
пуст; вердикт-ключи и порядок под-гейтов не тронуты (TC-07). Подтверждено независимой проверкой
diff, не только тестом.
- **AC-4 (обязательный регресс-тест)** ✓ — ось добавлена в `.openclaw/agents/reviewer.md`
(«фикс без теста-фиксатора → finding ≥P1»); `04-test-plan.yaml` несёт требование. (Сам ORCH-019 —
feature, не bugfix, поэтому правило к нему не применяется; покрытие — 46 содержательных тестов.)
- **AC-5 (эскалация)** ✓ — `POST /bug-fast-track/escalate` (`db.set_task_track 'bug'→'full'`,
Telegram+Plane-коммент, never-raise) + self-escalate мини-аналитика (`analyst.md`).
- **AC-6 (fail-safe / нулевая регрессия)** ✓ — `bug_fast_track_enabled` kill-switch; все публичные
функции leaf'а never-raise → False (full cycle); `get_task_track` деградирует в `'full'`.
Дефолт `True` согласован со всеми sibling-флагами (serial_gate/auto_label/coverage/stop/… все
`= True` при пустом scope = self-hosting only).
- **AC-7 (наблюдаемость)** ✓ — read-only блок `bug_fast_track` в `GET /queue` (`snapshot()`,
never-raise) + отметка `🐞` в Telegram-карточке (never-raise) + лог-строки на решение.
- **AC-8 (аддитивность / self-hosting)** ✓ — `_ensure_column(tasks, track, "TEXT DEFAULT 'full'")`
идемпотентна (TC-15); прод-контейнер/`main` не трогаются; полный `tests/` зелёный.
- **AC-9 (композиция)** ✓ — serial-gate/auto-label/coverage/merge — тест композиции зелёный
(TC-14); override применяется ДО всех deploy-edge под-гейтов.
### 2. Соответствие ADR
Реализация точно следует ADR-001 (D1D8): leaf `src/bug_fast_track.py`, колонка `tasks.track`,
override в `advance_stage`, эскалация-эндпоинт, область self-hosting-only. Сквозной ADR
`adr-0032-bug-fast-track.md` присутствует.
**Трассировка:** `advance_stage` несёт маркеры ORCH-088/089/027/059/094; врезка ORCH-019 добавляет
ветвление ТОЛЬКО на ребре выхода из `analysis` (до deploy-edge под-гейтов) — зафиксированные
инварианты (порядок под-гейтов, merge-lease, terminal-sync) не нарушены. Сверено по diff. Расширение
`mark_brd_review_ended` на `analysis → development` (ORCH-087 метрика) гейтов не касается.
### 3. Качество кода
- Leaf чист (импортирует только `config`, лениво `labels`/`db`/`qg.checks`), never-raise контракт
соблюдён везде, публичные функции снабжены docstrings. ✓
- Next-agent override (`next_stage == "development"`) безопасен: единственный путь к
`analysis → development` — сам багфикс-override (штатно `get_next_stage("analysis") == "architecture"`). ✓
- `get_task_by_work_item_id`/`add_comment`/`set_task_track`/`get_task_track` существуют и
совместимы по сигнатурам. ✓
### 4. Документация — обязательная проверка
`src/` изменён → документация ДОЛЖНА быть обновлена. **Обновлено в том же PR:**
- `docs/architecture/README.md` — раздел «Багфикс-трек (ORCH-019)» + блок `bug_fast_track` в `GET /queue`;
- `README.md` — таблица env (`ORCH_BUG_FAST_TRACK_*`) + обзорный раздел;
- `.env.example` — три новых переменных;
- `docs/architecture/adr/adr-0032-bug-fast-track.md` (сквозной) + `06-adr/ADR-001`;
- `docs/architecture/internals.md`, `CLAUDE.md`, `CHANGELOG.md` (`feat:`);
- `07-infra-requirements.md` / `08-data-requirements.md` / `10-tech-risks.md`;
- `.openclaw/agents/analyst.md` (lite-пакет + self-escalate) и `reviewer.md` (ось регресс-теста).
Все поверхности из §8 ТЗ покрыты. **Обзорная витрина README** — добавлен раздел, ничего из «Известных
ограничений» не оставлено открытым в нарушение ORCH-079.
## Findings
### P0 — Blocker
- (нет)
### P1 — Must fix
- (нет)
### P2 — Should fix
- (нет)
### P3 — Nice to have
- [ ] `snapshot.est_saved_architecture_runs == total_bug_tasks` считает ВСЕ багфикс-задачи, включая
`cancelled` (которые могли не дойти до пропуска `architecture`). Косметическая неточность метрики
экономии; на гейты/маршрут не влияет. Можно сузить до `stage NOT IN ('cancelled')` при случае.
## Документация
Обновлена полностью и согласованно во всех требуемых поверхностях (architecture/README, README env +
обзор, оба ADR, internals, CLAUDE.md, CHANGELOG, .env.example, промпты analyst/reviewer,
infra/data/risks). Расхождений код↔документация не обнаружено. Требований к доработке документации
нет.
## Вердикт
Нет findings уровня P0/P1; документация обновлена; корневой инвариант подтверждён независимой
проверкой diff и зелёным полным регрессом (1551 passed). → **APPROVED**.

View File

@@ -0,0 +1,84 @@
---
result: PASS # PASS | FAIL — машинный вердикт, UPPERCASE
work_item: ORCH-019
stage: testing
author_agent: tester
status: pass
created_at: 2026-06-10
model_used: claude-opus-4-8
type: test-report
work_item_id: ORCH-019
---
# Test Report — ORCH-019 — Багфикс-трек (упрощённый/дешёвый маршрут для багов)
## Окружение
- Python: 3.12.13
- pytest: 8.3.3 (plugins: cov-5.0.0, anyio-4.13.0, asyncio-0.23.8)
- Worktree: `/repos/_wt/orchestrator/feature_ORCH-019-` (ветка `feature/ORCH-019-`)
- Дата: 2026-06-10T00:53:34Z
- Предусловие: review `12-review.md` = `verdict: APPROVED`
## Smoke API (read-only)
| Endpoint | Результат | Примечание |
|----------|-----------|------------|
| `GET /health` | PASS | `{"status":"ok","service":"orchestrator"}` |
| `GET /status` | PASS | отвечает; ORCH-019 (task 84) виден на стадии `testing` |
| `GET /queue` | PASS | блок `serial_gate` присутствует (ORCH-088) ✓; `auto_labels` присутствует ✓ |
> Прод-контейнер (8500) исполняет код **до** ORCH-019 (фича ещё не задеплоена), поэтому блока
> `bug_fast_track` в живом `/queue` ожидаемо нет — это не регресс смока. Обязательные для смока
> блоки `serial_gate` и `auto_labels` присутствуют. Новый блок `bug_fast_track` верифицирован
> юнит/интеграционными тестами `test_queue_endpoint.py` (TC-13) на коде ветки. Smoke — read-only,
> прод-контейнер не трогался.
## Результаты — покрытие TC из `04-test-plan.yaml`
| TC ID | Описание (кратко) | Тип | Тесты | AC | Результат |
|-------|-------------------|-----|-------|----|-----------|
| TC-01 | `is_bug_task()` True для метки `Bug`; источник — Plane API, не payload | unit | `test_tc01_is_bug_task_true`, `test_tc01_label_from_plane_api_not_payload` | AC-1 | PASS |
| TC-02 | `is_bug_task()` False при отсутствии/неоднозначной метке/`labels=None` (fail-safe) | unit | `test_tc02_label_absent`, `test_tc02_labels_none`, `test_tc02_label_ambiguous`, `test_tc02_empty_label_config` | AC-1/AC-6 | PASS |
| TC-03 | `bug_fast_track_applies(repo)`: локальная область ПЕРВОЙ; выключенный флаг → без сети | unit | `test_tc03_empty_csv_self_hosting_only`, `test_tc03_csv_membership`, `test_tc03_killswitch_off_no_network` | AC-6 | PASS |
| TC-04 | never-raise: исключение в fetch labels → деградация в False (полный цикл) | unit | `test_tc04_is_bug_task_never_raises`, `test_tc04_applies_never_raises` | AC-6 | PASS |
| TC-05 | Маршрут: bug → next stage после analysis = `development`; не-баг = `architecture` | unit | `test_tc05_bug_task_skips_architecture`, `test_tc05_full_task_keeps_architecture`, `test_tc05_killswitch_off_bug_keeps_architecture`, `test_tc05_bug_only_affects_analysis_edge` | AC-2 | PASS |
| TC-06 | `STAGE_TRANSITIONS` структурно не изменён (анти-регресс) | unit | `test_tc06_stage_transitions_unchanged`, `test_tc06_get_next_stage_pure` | AC-2 | PASS |
| TC-07 | `QG_CHECKS`/сигнатуры `check_*`/вердикт-ключи не изменены (имя+регистр) | unit | `test_tc07_qg_checks_registry_unchanged`, `test_tc07_verdict_keys_preserved` | AC-3 | PASS |
| TC-08 | E2E багфикс-трек проходит development→…→deploy, минуя architecture, все гейты | integration | `test_tc08_bug_task_full_walk_skips_architecture` | AC-2/AC-3 | PASS |
| TC-09 | `start_pipeline`: метка Bug → bug-track; без метки → full-track | integration | `test_tc09_bug_label_creates_bug_track`, `test_tc09_no_label_creates_full_track` | AC-1 | PASS |
| TC-10 | Fail-safe: `enabled=False` → метка Bug идёт полным циклом (нулевая регрессия) | integration | `test_tc10_killswitch_off_bug_label_full_cycle` | AC-6 | PASS |
| TC-11 | Эскалация: `'bug'→'full'` → штатный маршрут с architecture | integration | `test_tc11_escalate_returns_to_full_cycle`, `test_tc11_escalate_unknown_work_item`, `test_tc11_escalate_missing_arg`, `test_tc11_escalate_idempotent_on_full` | AC-5 | PASS |
| TC-12 | `check_analysis_*` не блокирует ложно lite-пакет; не ослаблен для не-баг | unit | `test_tc12_bug_lite_package_with_all_four_passes`, `test_tc12_missing_file_still_fails_for_any_track`, `test_tc12_signature_has_no_track_param` | AC-3/FR-6 | PASS |
| TC-13 | `GET /queue` несёт read-only блок `bug_fast_track`; существующие ключи целы | integration | `test_queue_has_bug_fast_track_block_and_keeps_existing_keys`, `test_queue_bug_fast_track_counts_bug_tasks` | AC-7 | PASS |
| TC-14 | Композиция: bug-задача учтена serial-gate; autoApprove/autoDeploy применимы | integration | `test_tc14_bug_task_counts_as_active_in_serial_gate`, `test_tc14_bug_task_itself_gated_behind_predecessor`, `test_tc14_bug_task_claimable_once_predecessor_done`, `test_tc14_auto_label_applies_track_agnostic` | AC-9 | PASS |
| TC-15 | Миграция `tasks.track` аддитивна/идемпотентна; дефолт `'full'` | unit | `test_tc15_track_column_present_with_default`, `test_tc15_init_db_idempotent`, `test_tc15_helpers_round_trip`, `test_tc15_get_task_track_missing_row_failsafe` | AC-8 | PASS |
**Итог покрытия:** все 15 TC из `04-test-plan.yaml` выполнены и сопоставлены с критериями
`03-acceptance-criteria.md` (AC-1…AC-9). Непокрытых/пропущенных TC нет.
## Вывод pytest
### Целевые suite ORCH-019 (6 файлов + queue/migrations)
```
$ pytest tests/test_bug_fast_track.py tests/test_bug_fast_track_routing.py \
tests/test_bug_fast_track_gates.py tests/test_bug_fast_track_e2e.py \
tests/test_bug_fast_track_escalation.py tests/test_bug_fast_track_composition.py \
tests/test_queue_endpoint.py tests/test_db_migrations.py -v
...
======================== 46 passed, 1 warning in 2.51s =========================
```
46/46 целевых тестов — PASS.
### Полный регресс
```
$ pytest tests/ -q --tb=short
........................................................................ [100%]
1551 passed, 1 warning in 56.64s
```
1551/1551 — PASS, 0 failed. (Единственный warning — известный Pydantic V2 deprecation в
`src/config.py:8`, не относится к ORCH-019.)
## Итог
**PASS** — полный регресс (1551 passed) и целевые suites ORCH-019 (46 passed) зелёные; smoke API
(`/health`/`/status`/`/queue` с блоками `serial_gate`+`auto_labels`) — OK; все 15 TC выполнены и
сопоставлены с AC-1…AC-9. Корневой инвариант NFR-1 (неизменность `STAGE_TRANSITIONS`/`QG_CHECKS`/
вердикт-ключей) подтверждён анти-регресс-тестами TC-06/TC-07. → стадия переходит на `deploy-staging`.

View File

@@ -0,0 +1,12 @@
---
deploy_status: SUCCESS
work_item: ORCH-019
hook_exit_code: 0
deployed_by: deploy-finalizer
---
# Deploy log — ORCH-036 executable self-deploy
Прод-деплой завершён хост-хуком с exit-code `0` -> `deploy_status: SUCCESS`.
Вердикт зафиксирован детерминированным finalizer'ом (Фаза C), не LLM.

View File

@@ -0,0 +1,51 @@
---
staging_status: SUCCESS
work_item: ORCH-019
stage: deploy-staging
author_agent: deployer
status: success
created_at: 2026-06-10
model_used: claude-opus-4-8
timestamp: 2026-06-10T00:56:51Z
base_url: http://localhost:8501
---
# Staging Gate Log
Staging test suite completed against the live `orchestrator-staging` environment (port 8501),
run inside the `orchestrator-staging` container (canonical path, ORCH-048):
```
docker exec orchestrator-staging \
python3 /repos/orchestrator/scripts/staging_check.py \
--base-url http://localhost:8501 --mode stub
```
**Result: 8/10 checks PASS — exit code 0 → SUCCESS.**
- REAL failed: **none**
- SANDBOX_INFRA waived (ORCH-061): C9a, C9b
INFRA-WAIVED: C9a Branch appears in orchestrator-sandbox, C9b Analyst job enqueued in staging queue (known sandbox-infra; real checks green)
VERDICT: SUCCESS (exit 0) — SUCCESS (infra-waived): ['C9a Branch appears in orchestrator-sandbox', 'C9b Analyst job enqueued in staging queue'] are known sandbox-infra checks; all real checks green
## Check breakdown
| Block | Check | Result |
|-------|-------|--------|
| A SMOKE | A1 GET /health → 200 status=ok | ✓ PASS |
| A SMOKE | A2 GET /queue → 200 with counts/max_concurrency/resilience | ✓ PASS |
| A SMOKE | A3 ORCH_STAGING=true (not prod) | ✓ PASS |
| B ACCESS | B4 Plane: sandbox project accessible | ✓ PASS |
| B ACCESS | B5 Gitea: orchestrator-sandbox accessible, push=true | ✓ PASS |
| B ACCESS | B6 Registry: sandbox present, prod ET/ORCH absent | ✓ PASS |
| C E2E | C7 Create issue in Plane SANDBOX | ✓ PASS |
| C E2E | C8 Trigger pipeline via /webhook/plane | ✓ PASS |
| C E2E | C9a Branch appears in orchestrator-sandbox | ✗ FAIL (INFRA-WAIVED) |
| C E2E | C9b Analyst job enqueued in staging queue | ✗ FAIL (INFRA-WAIVED) |
Cleanup: Plane issue deleted (HTTP 204); no branch to delete.
Exit-code → verdict mapping unchanged: exit 0 → `staging_status: SUCCESS`. Waived checks are not
re-judged (trust the exit code; the two infra-only checks C9a/C9b depend on SANDBOX bot accounts
being project members, not on the pipeline). Staging gate **PASSED**; task advances to `deploy`.

View File

@@ -0,0 +1,14 @@
---
post_deploy_status: HEALTHY
action_taken: NONE
work_item: ORCH-019
window_s: 900
checks_total: 30
checks_failed: 0
---
# Post-deploy log — ORCH-021 post-deploy monitor
Наблюдение прода завершено: `post_deploy_status: HEALTHY`, `action_taken: NONE`.
Окно наблюдения: 900s; опросов всего: 30, из них с провалом: 0.

View File

@@ -0,0 +1,12 @@
---
deploy_status: SUCCESS
work_item: ORCH-057
hook_exit_code: 0
deployed_by: deploy-finalizer
---
# Deploy log — ORCH-036 executable self-deploy
Прод-деплой завершён хост-хуком с exit-code `0` -> `deploy_status: SUCCESS`.
Вердикт зафиксирован детерминированным finalizer'ом (Фаза C), не LLM.

166
src/bug_fast_track.py Normal file
View File

@@ -0,0 +1,166 @@
"""ORCH-019: bug-fast-track — a cheaper/shorter pipeline route for bug-fix tasks.
Leaf module — pure, unit-testable logic over the config flags + the proven Plane
label apparatus (``labels.has_label`` -> ``plane_sync``, ORCH-089). Mirrors the
leaf pattern of ``src/labels.py`` / ``src/serial_gate.py``: imports only
``config`` (and lazily ``labels`` / ``db`` / ``qg.checks``), never
``stage_engine`` / ``launcher``.
What it decides (ADR-001):
* Whether the bug-fast-track is in scope for a repo (``bug_fast_track_applies``)
— a LOCAL, network-free check evaluated FIRST.
* Whether a given Plane issue carries the ``Bug`` label (``is_bug_task``) — the
only network call, made ONLY after ``applies()`` is True, so a disabled
kill-switch costs zero network and yields zero regression (AC-6).
* Whether a task's stored track skips the ``architecture`` stage
(``skips_architecture``) — a pure predicate over the DB-stored ``track``,
read in the hot ``advance_stage`` path WITHOUT any network call (NFR-4).
never-raise contract (BR-6/AC-6, fail-safe to the FULL cycle): every public
function degrades to "full cycle" on ANY error / ambiguity / Plane
unavailability / disabled flag. There is NO fail-open here — the conservative
default is always the full pipeline (with ``architecture``), so an error can
never silently skip a stage.
"""
from __future__ import annotations
import logging
from .config import settings
logger = logging.getLogger("orchestrator.bug_fast_track")
# ---------------------------------------------------------------------------
# Scope / kill-switch (mirrors _auto_label_applies / serial_gate_applies)
# ---------------------------------------------------------------------------
def bug_fast_track_applies(repo: str) -> bool:
"""Whether the bug-fast-track is REAL for ``repo`` (ADR-001 D6 / AC-6).
* ``bug_fast_track_enabled=False`` -> always False (kill-switch; start and
routing are 1:1 as before ORCH-019, and — crucially — ``has_label`` is
never consulted, so no new network call on start, AC-6).
* ``bug_fast_track_repos`` (CSV) non-empty -> real only for the listed repos.
* empty CSV -> self-hosting only (``orchestrator``) — the safe default (the
track is first burnt in on the orchestrator itself, where the `Bug` label
is guaranteed to exist; enduro opts in via an explicit CSV entry).
Checked FIRST (local, network-free); never raises -> False on error (degrade
to "full cycle", which matches the kill-switch-off behaviour).
"""
try:
if not getattr(settings, "bug_fast_track_enabled", False):
return False
raw = (getattr(settings, "bug_fast_track_repos", "") or "").strip()
if raw:
allowed = {r.strip().lower() for r in raw.split(",") if r.strip()}
return (repo or "").strip().lower() in allowed
# Lazy import keeps this module a leaf (avoids importing qg at load).
from .qg.checks import is_self_hosting_repo
return is_self_hosting_repo(repo)
except Exception as e: # noqa: BLE001 - never-raise -> full cycle
logger.warning("bug_fast_track_applies error for %s: %s", repo, e)
return False
# ---------------------------------------------------------------------------
# Classification (the ONLY network call; ADR-001 D1)
# ---------------------------------------------------------------------------
def is_bug_task(work_item_id: str, project_id: str | None = None) -> bool:
"""True iff the issue carries the configured ``Bug`` label (Plane API source).
``bug_fast_track_applies`` is assumed already True (checked by the caller —
the gate idiom ``applies(repo) and is_bug_task(...)`` short-circuits before any
network call when the kill-switch is off). Delegates to the proven
``labels.has_label`` (fetch_issue_labels + get_project_labels, normalization,
TTL-cache, source-of-truth = Plane API, not the webhook payload).
Any error / ambiguity / Plane unavailability -> **False** (fail-safe -> full
cycle, never silently fast-track on doubt).
"""
try:
label = (getattr(settings, "bug_fast_track_label", "") or "").strip()
if not label:
return False
from . import labels
return bool(labels.has_label(work_item_id, label, project_id))
except Exception as e: # noqa: BLE001 - never-raise -> full cycle
logger.warning(
"is_bug_task error for %s -> fail-safe (full cycle): %s", work_item_id, e
)
return False
# ---------------------------------------------------------------------------
# Routing predicate (pure, DB-backed; hot path — NO network, NFR-4) — ADR-001 D3
# ---------------------------------------------------------------------------
def skips_architecture(track: str | None) -> bool:
"""Whether a task with stored ``track`` skips the ``architecture`` stage.
Pure predicate (no I/O): True iff the kill-switch is on AND ``track == 'bug'``.
Used by ``advance_stage`` on the analysis-exit edge to map
``analysis -> architecture`` to ``analysis -> development`` for a bug task.
A disabled flag -> always False (1:1 prior routing); any error -> False
(fail-safe -> full cycle).
"""
try:
if not getattr(settings, "bug_fast_track_enabled", False):
return False
return (track or "").strip().lower() == "bug"
except Exception as e: # noqa: BLE001 - never-raise -> full cycle
logger.warning("skips_architecture error for track=%r: %s", track, e)
return False
# ---------------------------------------------------------------------------
# Observability snapshot for GET /queue (ADR-001 D7)
# ---------------------------------------------------------------------------
def snapshot() -> dict:
"""Read-only bug-fast-track summary for GET /queue (additive block). never-raise.
Surfaces the flags + a savings metric derived from the existing telemetry: the
count of tasks on the bug track and the number of ``architecture`` agent runs
those tasks structurally skipped (one per bug task = ``est_saved_architecture_runs``).
Any error -> a minimal dict with the flags (never crashes the endpoint).
"""
try:
enabled = bool(getattr(settings, "bug_fast_track_enabled", False))
except Exception: # noqa: BLE001
enabled = False
try:
label = getattr(settings, "bug_fast_track_label", "Bug") or "Bug"
except Exception: # noqa: BLE001
label = "Bug"
try:
repos_cfg = getattr(settings, "bug_fast_track_repos", "") or ""
except Exception: # noqa: BLE001
repos_cfg = ""
active_bug_tasks = 0
total_bug_tasks = 0
try:
from . import db
conn = db.get_db()
try:
# ORCH-090 terminal set {done,cancelled}: "active" = not terminal.
row = conn.execute(
"SELECT "
" COUNT(*) AS total, "
" SUM(CASE WHEN stage NOT IN ('done','cancelled') THEN 1 ELSE 0 END) AS active "
"FROM tasks WHERE track = 'bug'"
).fetchone()
if row:
total_bug_tasks = int(row["total"] or 0)
active_bug_tasks = int(row["active"] or 0)
finally:
conn.close()
except Exception as e: # noqa: BLE001
logger.warning("bug_fast_track snapshot count error: %s", e)
return {
"enabled": enabled,
"label": label,
"repos": repos_cfg,
"active_bug_tasks": active_bug_tasks,
"total_bug_tasks": total_bug_tasks,
# Each bug task skips exactly one `architecture` stage (one architect agent
# run + ADR). This is the structural savings the track buys (FR-7 / AC-7).
"est_saved_architecture_runs": total_bug_tasks,
}

View File

@@ -794,6 +794,34 @@ class Settings(BaseSettings):
auto_label_repos: str = ""
auto_label_states_ttl_s: int = 300
# ORCH-019: bug-fast-track — a cheaper/shorter pipeline route for bug-fix tasks.
# A task carrying the Plane label `bug_fast_track_label` (default `Bug`) skips
# the whole `architecture` stage (one opus `architect` run + ADR + the
# check_architecture_done exit-gate): the routing-override in advance_stage maps
# the analysis -> architecture edge to analysis -> development for a task whose
# tasks.track == 'bug'. EVERY Quality Gate / sub-gate (CI/review/tester/staging/
# deploy + security/merge/coverage/image-freshness/merge-verify) runs UNCHANGED
# — the route is a scheduler property, NOT a gate (root invariant NFR-1).
# Recognition reuses the proven ORCH-089 label apparatus (labels.has_label ->
# plane_sync), read ONLY in start_pipeline (never in the hot claim_next_job).
# Additive leaf (src/bug_fast_track.py, never-raise) + an additive idempotent
# tasks.track column; STAGE_TRANSITIONS / QG_CHECKS / check_* / verdict-keys are
# NOT touched. fail-safe -> full cycle on any error/ambiguity/disabled flag. See
# docs/work-items/ORCH-019/06-adr/ADR-001-bug-fast-track.md and the cross-cutting
# docs/architecture/adr/adr-0032-bug-fast-track.md.
# bug_fast_track_enabled -> kill-switch (env ORCH_BUG_FAST_TRACK_ENABLED).
# False -> start_pipeline AND advance_stage are 1:1 as
# before ORCH-019 (skips_architecture always False,
# has_label never consulted) — zero regression (AC-6).
# bug_fast_track_label -> Plane label name that activates the track (env
# ORCH_BUG_FAST_TRACK_LABEL; default `Bug`).
# bug_fast_track_repos -> CSV scope (env ORCH_BUG_FAST_TRACK_REPOS). Empty ->
# self-hosting only (orchestrator), the safe default
# (D6); non-empty -> only the listed repos.
bug_fast_track_enabled: bool = True
bug_fast_track_label: str = "Bug"
bug_fast_track_repos: str = ""
# Telegram notifications
telegram_bot_token: str = ""
telegram_chat_id: str = ""

View File

@@ -140,6 +140,13 @@ def init_db():
# irreversible step finishes honestly, then applied.
_ensure_column(conn, "tasks", "cancelled_at", "TEXT")
_ensure_column(conn, "tasks", "cancel_requested_at", "TEXT")
# ORCH-019 (08-data-requirements.md): bug-fast-track task type. Additive,
# idempotent (_ensure_column is a no-op once present) -> safe on the live shared
# prod DB (enduro untouched). Values: 'full' (DEFAULT — ALL existing and non-bug
# tasks) | 'bug' (a task carrying the Plane `Bug` label, set in start_pipeline
# after a successful atomic create). Read in advance_stage for the routing-override
# (skips architecture) — from the DB, NEVER from the network (NFR-4).
_ensure_column(conn, "tasks", "track", "TEXT DEFAULT 'full'")
# ORCH-026 (Level B): declarative task dependencies. job_deps stores the
# directed edge "task_id (B) is blocked-by depends_on_task_id (A)". The
# scheduler gate in claim_next_job keeps B queued until every A reaches
@@ -487,6 +494,48 @@ def update_task_stage(task_id: int, stage: str):
conn.close()
# ---------------------------------------------------------------------------
# ORCH-019: bug-fast-track task type (tasks.track) helpers
# ---------------------------------------------------------------------------
def set_task_track(task_id: int, track: str) -> None:
"""ORCH-019: persist the task's pipeline track ('full' | 'bug').
Idempotent overwrite. Called from start_pipeline (after a successful atomic
create, when the issue carries the `Bug` label) and from the escalate endpoint
(reset 'bug' -> 'full' to return a complex bug to the full cycle).
"""
conn = get_db()
try:
conn.execute(
"UPDATE tasks SET track = ? WHERE id = ?", (track, task_id)
)
conn.commit()
finally:
conn.close()
def get_task_track(task_id: int) -> str:
"""ORCH-019: read the task's pipeline track; missing/NULL -> 'full' (fail-safe).
Read in the hot advance_stage path for the routing-override (skips architecture).
A non-existent row, a NULL value, or any read error degrades to 'full' so a bug
can never be created by accident (fail-safe -> full cycle).
"""
try:
conn = get_db()
try:
row = conn.execute(
"SELECT track FROM tasks WHERE id = ?", (task_id,)
).fetchone()
finally:
conn.close()
if not row:
return "full"
return row["track"] or "full"
except Exception: # noqa: BLE001 - fail-safe -> full cycle
return "full"
# ---------------------------------------------------------------------------
# Telegram live tracker helpers (feat/telegram-live-tracker)
# ---------------------------------------------------------------------------

View File

@@ -212,6 +212,7 @@ async def queue():
from . import fs_normalize
from . import labels
from . import cancel
from . import bug_fast_track
from .disk_watchdog import disk_watchdog
from .build_cache_pruner import build_cache_pruner
return {
@@ -243,6 +244,10 @@ async def queue():
# repo scope, cancelled/deferred counts, recent cancellations. Additive block;
# never-raise.
"stop": cancel.snapshot(),
# ORCH-019 (FR-7 / AC-7): bug-fast-track observability (read-only) —
# kill-switch, label, scope, bug-task counts + the structural savings metric
# (architecture stages skipped). Additive block; never-raise.
"bug_fast_track": bug_fast_track.snapshot(),
# ORCH-063 (FR-6 / AC-7): disk-watchdog observability (read-only) —
# enabled, threshold, interval, last measurement per host-path. Additive
# block; never-raise (status() returns {"enabled": ...} minimum on error).
@@ -343,3 +348,45 @@ async def coverage_set_baseline(repo: str = "", value: float | None = None):
repo = repo.strip()
ok = db.set_coverage_baseline(repo, value, sha="manual-override")
return {"ok": ok, "repo": repo, "baseline": db.get_coverage_baseline(repo)}
@app.post("/bug-fast-track/escalate")
async def bug_fast_track_escalate(work_item: str = ""):
"""ORCH-019 (FR-5 / AC-5, ADR-001 D5): escalate a bug-fast-track task to the
full cycle (return it to the route WITH `architecture`).
Operator path for a bug that turned out to be complex / architectural / visual
(needs an ADR or a mock): reset ``tasks.track`` 'bug' -> 'full'. Apply while the
task is still in `analysis` (before its exit) — the next advance_stage then routes
analysis -> architecture normally. By образцу ``POST /serial-gate/unfreeze`` /
``POST /coverage/baseline``. never-raise.
"""
from . import db
if not work_item or not work_item.strip():
return {"ok": False, "error": "missing 'work_item'", "work_item": work_item}
work_item = work_item.strip()
task = db.get_task_by_work_item_id(work_item)
if not task:
return {"ok": False, "error": "unknown work_item", "work_item": work_item}
prev_track = task.get("track") or "full"
db.set_task_track(task["id"], "full")
if prev_track == "bug":
try:
from .notifications import send_telegram
send_telegram(
f"🐞➡️ {work_item}: эскалация в ПОЛНЫЙ цикл "
f"(багфикс-трек снят, стадия architecture восстановлена)."
)
except Exception:
pass
try:
from .plane_sync import add_comment
add_comment(
work_item,
"🐞➡️ Эскалация: задача возвращена в полный цикл "
"(багфикс-трек снят, стадия architecture восстановлена).",
author="analyst",
)
except Exception:
pass
return {"ok": True, "work_item": work_item, "track": "full", "was": prev_track}

View File

@@ -452,10 +452,18 @@ def render_task_tracker(task_id: int) -> str:
task_repo = _row_get(task, "repo")
task_issue_id = _row_get(task, "plane_issue_id")
num_html = plane_issue_link(work_item_id, plane_issue_id=task_issue_id, repo=task_repo)
# ORCH-019 (D7): mark a bug-fast-track task with a \ud83d\udc1e in the header. Optional,
# never-raise \u2014 any error simply omits the marker (the card always renders).
bug_marker = ""
try:
if (_row_get(task, "track") or "").strip().lower() == "bug":
bug_marker = "\U0001f41e "
except Exception:
bug_marker = ""
header = (
f"\U0001f389 {num_html} \u00b7 {esc_title} \u2014 \u0413\u041e\u0422\u041e\u0412\u041e"
f"\U0001f389 {bug_marker}{num_html} \u00b7 {esc_title} \u2014 \u0413\u041e\u0422\u041e\u0412\u041e"
if done
else f"\U0001f6e0\ufe0f {num_html} \u00b7 {esc_title}"
else f"\U0001f6e0\ufe0f {bug_marker}{num_html} \u00b7 {esc_title}"
)
bar = "\u2501" * 22
# ORCH-067 (req 2): a Plane-status line (model ORCH-066) under the header.

View File

@@ -30,7 +30,7 @@ import os
import time
from dataclasses import dataclass, field
from .db import get_db, update_task_stage, enqueue_job
from .db import get_db, update_task_stage, enqueue_job, get_task_track
from .stages import get_next_stage, get_qg_for_stage, get_agent_for_stage
from .git_worktree import get_worktree_path
from .review_parse import extract_review_findings, extract_test_failures
@@ -40,6 +40,7 @@ from . import merge_gate
from . import self_deploy
from . import post_deploy
from . import labels
from . import bug_fast_track
from .notifications import (
notify_stage_change,
notify_qg_failure,
@@ -212,6 +213,25 @@ def advance_stage(
try:
qg_name = get_qg_for_stage(current_stage)
next_stage = get_next_stage(current_stage)
# --- ORCH-019 bug-fast-track routing-override (ADR-001 D3) ------------
# A task carrying the Plane `Bug` label is stored as tasks.track='bug' in
# start_pipeline. On the analysis-EXIT edge we map analysis -> architecture
# to analysis -> development, so a bug skips the whole `architecture` stage
# (one opus architect run + ADR + check_architecture_done). This is a pure
# routing-override: STAGE_TRANSITIONS / get_next_stage / get_agent_for_stage
# stay 1:1, and the track is read from the DB (no network in this hot path,
# NFR-4). For a non-bug task (track='full', the DEFAULT) the route is
# byte-for-byte unchanged. The `track` is reused below for the next-agent
# override and the brd-review-clock stamp.
track = get_task_track(task_id)
if current_stage == "analysis" and bug_fast_track.skips_architecture(track):
next_stage = "development"
logger.info(
f"Task {task_id}: bug-fast-track -> analysis -> development "
f"(skipping architecture, ORCH-019)"
)
result.qg_name = qg_name
result.to_stage = next_stage
@@ -383,7 +403,11 @@ def advance_stage(
# Telegram live tracker: the analysis->architecture advance is the human
# Approved gate clearing -> stamp the END of "Ревью БРД" (the only
# human time). Idempotent: only the first stamp counts.
if current_stage == "analysis" and next_stage == "architecture":
# ORCH-019 (ADR-001 D3): for a bug-fast-track task the analysis-exit edge
# lands on `development` (not `architecture`), so the brd-review-clock end
# stamp must trigger on BOTH targets — otherwise "твоё время" (ORCH-087)
# would never close on the bug track. This does not touch any gate.
if current_stage == "analysis" and next_stage in ("architecture", "development"):
try:
from .db import mark_brd_review_ended
mark_brd_review_ended(task_id)
@@ -462,6 +486,12 @@ def advance_stage(
# --- Launch the next agent (ORCH-4 fix: current_stage, not next) -----
next_agent = get_agent_for_stage(current_stage)
# ORCH-019 (ADR-001 D3): get_agent_for_stage('analysis') is 'architect'; for a
# bug-fast-track task we skip the architect run entirely and launch the
# developer directly (mirrors the next_stage override above). get_agent_for_stage
# stays pure (1:1) — the override lives here, NOT in stages.py.
if current_stage == "analysis" and next_stage == "development":
next_agent = "developer"
if next_agent:
task_desc = (
f"Work item: {work_item_id}\nRepo: {repo}\n"

View File

@@ -18,6 +18,7 @@ from ..db import (
enqueue_job,
insert_event_dedup,
create_task_atomic,
set_task_track,
)
from ._dedup import plane_delivery_id
from ..stages import get_next_stage, get_agent_for_stage, get_qg_for_stage, get_previous_stage
@@ -648,6 +649,42 @@ async def start_pipeline(data: dict, project_id: str = ""):
return
task_id = task_row["id"]
# ORCH-019 (FR-1/FR-2, ADR-001 D1/D2): classify the task as a bug-fix and put it
# on the cheaper bug-fast-track (skips the `architecture` stage downstream). The
# gate idiom is `applies(repo) and is_bug_task(...)`: the LOCAL, network-free
# `bug_fast_track_applies` is checked FIRST so a disabled kill-switch / out-of-scope
# repo costs ZERO network (no has_label call). The Plane `Bug` label is the source
# of truth (read here at start, NEVER in the hot claim_next_job — NFR-4); the type
# is persisted in tasks.track so advance_stage routes off the DB, not the network.
# never-raise / fail-safe: ANY error -> task stays track='full' (full cycle, AC-6).
try:
from .. import bug_fast_track
if bug_fast_track.bug_fast_track_applies(repo) and bug_fast_track.is_bug_task(
work_item_id, plane_project_id
):
set_task_track(task_id, "bug")
logger.info(
f"Task {work_item_id}: classified as BUG -> bug-fast-track "
f"(architecture stage will be skipped, ORCH-019)"
)
try:
from ..plane_sync import add_comment as _bug_comment
_bug_comment(
work_item_id,
"\U0001f41e Багфикс-трек: "
"упрощённый маршрут "
"(пропуск стадии architecture). "
"Все Quality Gate исполняются.",
author="analyst",
)
except Exception:
pass
except Exception as e:
logger.warning(
f"Task {work_item_id}: bug-fast-track classification skipped "
f"(fail-safe -> full cycle): {e}"
)
# ORCH-088 (FR-1/AC-6, ADR-001 D1): DEFER the branch cut for an applicable repo.
# Creating the Gitea branch here (T0, issue -> analysis) would cut it from `main`
# BEFORE the predecessor is merged -> stale base. When the serial gate applies we

View File

@@ -0,0 +1,168 @@
"""ORCH-019 — src/bug_fast_track.py: bug-fast-track pure logic (never-raise, fail-safe).
Covers (04-test-plan.yaml):
TC-01 is_bug_task() True for an issue carrying the `Bug` label (label read from
the Plane API via labels.has_label, NOT the webhook payload).
TC-02 is_bug_task() False on missing/ambiguous label or labels=None (fail-safe).
TC-03 bug_fast_track_applies(): the LOCAL scope (enabled + CSV repos) is checked
FIRST, before any network; disabled flag -> False without has_label.
TC-04 never-raise: an exception in the label apparatus degrades is_bug_task to
False (full cycle), never propagates.
"""
import os
import tempfile
import pytest
os.environ.setdefault(
"ORCH_DB_PATH", os.path.join(tempfile.gettempdir(), "test_bug_fast_track.db")
)
os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token")
os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token")
from src import bug_fast_track # noqa: E402
from src import plane_sync # noqa: E402
from src import config as cfg # noqa: E402
@pytest.fixture(autouse=True)
def enabled_self_hosting(monkeypatch):
monkeypatch.setattr(cfg.settings, "bug_fast_track_enabled", True, raising=False)
monkeypatch.setattr(cfg.settings, "bug_fast_track_label", "Bug", raising=False)
monkeypatch.setattr(cfg.settings, "bug_fast_track_repos", "", raising=False)
# Keep _resolve_project_id offline-deterministic (mirrors test_labels.py).
monkeypatch.setattr(plane_sync, "_resolve_project_id", lambda w=None, p=None: "proj-1")
yield
# --- TC-01: classification True --------------------------------------------
def test_tc01_is_bug_task_true(monkeypatch):
monkeypatch.setattr(plane_sync, "fetch_issue_labels", lambda w, p=None: ["uuid-BUG"])
monkeypatch.setattr(plane_sync, "get_project_labels", lambda pid: {"bug": "uuid-BUG"})
assert bug_fast_track.is_bug_task("ORCH-1", "proj-1") is True
def test_tc01_label_from_plane_api_not_payload(monkeypatch):
"""The decision comes from labels.has_label (Plane API), independent of any
webhook payload field — a payload `type` is irrelevant."""
seen = {"fetch": 0}
def fetch(w, p=None):
seen["fetch"] += 1
return ["uuid-BUG"]
monkeypatch.setattr(plane_sync, "fetch_issue_labels", fetch)
monkeypatch.setattr(plane_sync, "get_project_labels", lambda pid: {"bug": "uuid-BUG"})
assert bug_fast_track.is_bug_task("ORCH-1", "proj-1") is True
assert seen["fetch"] == 1 # the Plane API WAS consulted
# --- TC-02: fail-safe on absent / ambiguous / None -------------------------
def test_tc02_label_absent(monkeypatch):
monkeypatch.setattr(plane_sync, "fetch_issue_labels", lambda w, p=None: ["uuid-OTHER"])
monkeypatch.setattr(plane_sync, "get_project_labels", lambda pid: {"bug": "uuid-BUG"})
assert bug_fast_track.is_bug_task("ORCH-1", "proj-1") is False
def test_tc02_labels_none(monkeypatch):
monkeypatch.setattr(plane_sync, "fetch_issue_labels", lambda w, p=None: None)
monkeypatch.setattr(plane_sync, "get_project_labels", lambda pid: {"bug": "uuid-BUG"})
assert bug_fast_track.is_bug_task("ORCH-1", "proj-1") is False
def test_tc02_label_ambiguous(monkeypatch):
monkeypatch.setattr(plane_sync, "fetch_issue_labels", lambda w, p=None: ["uuid-BUG"])
monkeypatch.setattr(
plane_sync, "get_project_labels", lambda pid: {"bug": "__AMBIGUOUS__"}
)
assert bug_fast_track.is_bug_task("ORCH-1", "proj-1") is False
def test_tc02_empty_label_config(monkeypatch):
monkeypatch.setattr(cfg.settings, "bug_fast_track_label", "", raising=False)
monkeypatch.setattr(plane_sync, "fetch_issue_labels", lambda w, p=None: ["uuid-BUG"])
monkeypatch.setattr(plane_sync, "get_project_labels", lambda pid: {"bug": "uuid-BUG"})
assert bug_fast_track.is_bug_task("ORCH-1", "proj-1") is False
# --- TC-03: local scope first (CSV + self-hosting + kill-switch) ------------
def test_tc03_empty_csv_self_hosting_only(monkeypatch):
monkeypatch.setattr(cfg.settings, "bug_fast_track_repos", "", raising=False)
assert bug_fast_track.bug_fast_track_applies("orchestrator") is True
assert bug_fast_track.bug_fast_track_applies("enduro-trails") is False
def test_tc03_csv_membership(monkeypatch):
monkeypatch.setattr(cfg.settings, "bug_fast_track_repos", "enduro-trails, foo", raising=False)
assert bug_fast_track.bug_fast_track_applies("enduro-trails") is True
assert bug_fast_track.bug_fast_track_applies("foo") is True
# orchestrator is NOT in the explicit CSV -> out of scope.
assert bug_fast_track.bug_fast_track_applies("orchestrator") is False
def test_tc03_killswitch_off_no_network(monkeypatch):
"""The gate idiom `applies(repo) and is_bug_task(...)` short-circuits before any
network call when the kill-switch is off (AC-6)."""
monkeypatch.setattr(cfg.settings, "bug_fast_track_enabled", False, raising=False)
called = {"fetch": 0}
def spy(*a, **k):
called["fetch"] += 1
return ["uuid-BUG"]
monkeypatch.setattr(plane_sync, "fetch_issue_labels", spy)
repo = "orchestrator"
fired = bug_fast_track.bug_fast_track_applies(repo) and bug_fast_track.is_bug_task(
"ORCH-1", "proj-1"
)
assert fired is False
assert called["fetch"] == 0 # is_bug_task never reached -> zero network
# --- TC-04: never-raise -----------------------------------------------------
def test_tc04_is_bug_task_never_raises(monkeypatch):
def boom(*a, **k):
raise RuntimeError("plane down")
monkeypatch.setattr(plane_sync, "fetch_issue_labels", boom)
monkeypatch.setattr(plane_sync, "get_project_labels", lambda pid: {"bug": "uuid-BUG"})
# Degrades to False (full cycle), no exception.
assert bug_fast_track.is_bug_task("ORCH-1", "proj-1") is False
def test_tc04_applies_never_raises(monkeypatch):
# A repos config whose access explodes still yields False, not a crash.
class _Poisoned:
bug_fast_track_enabled = True
@property
def bug_fast_track_repos(self):
raise RuntimeError("boom")
monkeypatch.setattr(bug_fast_track, "settings", _Poisoned(), raising=False)
assert bug_fast_track.bug_fast_track_applies("orchestrator") is False
# --- skips_architecture predicate ------------------------------------------
def test_skips_architecture_bug(monkeypatch):
assert bug_fast_track.skips_architecture("bug") is True
assert bug_fast_track.skips_architecture("BUG") is True
def test_skips_architecture_full(monkeypatch):
assert bug_fast_track.skips_architecture("full") is False
assert bug_fast_track.skips_architecture(None) is False
assert bug_fast_track.skips_architecture("") is False
def test_skips_architecture_killswitch_off(monkeypatch):
monkeypatch.setattr(cfg.settings, "bug_fast_track_enabled", False, raising=False)
# Even a stored 'bug' track is inert when the kill-switch is off (1:1 routing).
assert bug_fast_track.skips_architecture("bug") is False
# --- snapshot ---------------------------------------------------------------
def test_snapshot_never_raises():
snap = bug_fast_track.snapshot()
assert set(snap) >= {
"enabled", "label", "repos",
"active_bug_tasks", "total_bug_tasks", "est_saved_architecture_runs",
}

View File

@@ -0,0 +1,87 @@
"""ORCH-019 — composition with ORCH-088 serial-gate / ORCH-089 auto-label (AC-9).
Covers (04-test-plan.yaml):
TC-14 A bug-fast-track task is an ORDINARY repo task for the serial gate
(ORCH-088): it counts as an active task and is gated like any other — it
does NOT bypass serialisation. autoApprove/autoDeploy (ORCH-089) apply on
the bug track (scope is repo-based, track-agnostic).
"""
import os
import tempfile
import pytest
os.environ["ORCH_DB_PATH"] = os.path.join(tempfile.gettempdir(), "test_bft_composition.db")
os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token")
os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token")
import src.db as db # noqa: E402
from src.db import init_db, get_db, enqueue_job, claim_next_job # noqa: E402
from src import serial_gate, labels, config as cfg # noqa: E402
@pytest.fixture(autouse=True)
def fresh_db(tmp_path, monkeypatch):
dbfile = tmp_path / "comp.db"
monkeypatch.setattr(db.settings, "db_path", str(dbfile))
monkeypatch.setattr(cfg.settings, "serial_gate_enabled", True, raising=False)
monkeypatch.setattr(cfg.settings, "serial_gate_repos", "", raising=False)
monkeypatch.setattr(cfg.settings, "serial_gate_freeze_enabled", False, raising=False)
monkeypatch.setattr(cfg.settings, "task_deps_enabled", False, raising=False)
monkeypatch.setattr(cfg.settings, "bug_fast_track_enabled", True, raising=False)
monkeypatch.setattr(cfg.settings, "auto_label_enabled", True, raising=False)
init_db()
yield
def _make_task(work_item_id, stage="analysis", repo="orchestrator", track="full"):
conn = get_db()
cur = conn.execute(
"INSERT INTO tasks (plane_id, work_item_id, repo, branch, stage, title, track) "
"VALUES (?, ?, ?, ?, ?, ?, ?)",
(work_item_id, work_item_id, repo, f"feature/{work_item_id}", stage, work_item_id, track),
)
tid = cur.lastrowid
conn.commit()
conn.close()
return tid
def test_tc14_bug_task_counts_as_active_in_serial_gate():
# An EARLIER bug task A (unfinished) must gate a later task B's analyst-job —
# a bug task does NOT bypass the serial gate.
_make_task("ORCH-301", stage="development", track="bug") # active bug predecessor
b = _make_task("ORCH-302", stage="analysis", track="full") # new task
enqueue_job("analyst", "orchestrator", "B", task_id=b)
assert claim_next_job() is None, "a bug task must gate a later analyst-job (no bypass)"
# The bug task is the active task in the snapshot.
per = serial_gate.snapshot()["per_repo"]["orchestrator"]
assert per["active_task"]["work_item_id"] == "ORCH-301"
def test_tc14_bug_task_itself_gated_behind_predecessor():
# The bug task is also HELD behind an earlier non-bug task (symmetry).
_make_task("ORCH-310", stage="development", track="full") # active predecessor
b = _make_task("ORCH-311", stage="analysis", track="bug") # new BUG task
enqueue_job("analyst", "orchestrator", "bug-B", task_id=b)
assert claim_next_job() is None, "a bug task is itself serialised behind the predecessor"
def test_tc14_bug_task_claimable_once_predecessor_done():
a = _make_task("ORCH-320", stage="development", track="full")
b = _make_task("ORCH-321", stage="analysis", track="bug")
jid = enqueue_job("analyst", "orchestrator", "bug-B", task_id=b)
assert claim_next_job() is None
# Finish A -> the bug task's analyst-job is now claimable.
conn = get_db()
conn.execute("UPDATE tasks SET stage='done' WHERE id=?", (a,))
conn.commit()
conn.close()
claimed = claim_next_job()
assert claimed is not None and claimed["id"] == jid
def test_tc14_auto_label_applies_track_agnostic(monkeypatch):
# autoApprove/autoDeploy scope is repo-based, independent of the bug track.
assert labels.auto_approve_applies("orchestrator") is True
assert labels.auto_deploy_applies("orchestrator") is True

View File

@@ -0,0 +1,184 @@
"""ORCH-019 — bug-fast-track end-to-end / start_pipeline integration.
Covers (04-test-plan.yaml):
TC-08 E2E: a bug task walks development -> review -> testing -> deploy-staging ->
deploy -> done with EVERY edge gate executed, NEVER entering architecture.
TC-09 start_pipeline: an issue with the `Bug` label (flag on, repo in scope) is
created on the bug-fast-track (tasks.track='bug'); an issue without it is
created on the full cycle (track='full').
TC-10 Fail-safe: with bug_fast_track_enabled=False a `Bug`-labelled issue is
created on the full cycle (track='full'), is_bug_task never consulted.
"""
import os
import tempfile
import pytest
_test_db = os.path.join(tempfile.gettempdir(), "test_bug_fast_track_e2e.db")
os.environ["ORCH_DB_PATH"] = _test_db
os.environ["ORCH_REPOS_DIR"] = tempfile.gettempdir()
os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token")
os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token")
import src.db as db # noqa: E402
from src.db import init_db, get_db # noqa: E402
from src import stage_engine, config as cfg # noqa: E402
from src.stage_engine import advance_stage # noqa: E402
@pytest.fixture(autouse=True)
def fresh_db(monkeypatch, tmp_path):
dbfile = tmp_path / "e2e.db"
monkeypatch.setattr(db.settings, "db_path", str(dbfile))
monkeypatch.setattr(cfg.settings, "bug_fast_track_enabled", True, raising=False)
monkeypatch.setattr(cfg.settings, "bug_fast_track_repos", "", raising=False)
# Keep the edge sub-gates + self-deploy + serial gate inert so the PLAIN advance
# path runs deterministically and offline (we assert routing + gate execution,
# not the self-hosting deploy mechanics — those have their own suites).
for flag in (
"self_deploy_enabled", "security_gate_enabled", "merge_gate_enabled",
"coverage_gate_enabled", "image_freshness_enabled",
"post_deploy_monitor_enabled", "serial_gate_enabled",
):
monkeypatch.setattr(cfg.settings, flag, False, raising=False)
init_db()
yield
@pytest.fixture(autouse=True)
def silence_side_effects(monkeypatch):
for name in (
"notify_stage_change", "notify_qg_failure", "notify_approve_requested",
"send_telegram", "plane_notify_stage", "plane_notify_qg", "plane_add_comment",
"set_issue_in_review", "set_issue_needs_input", "set_issue_in_progress",
"set_issue_blocked", "set_issue_done", "set_issue_analysis",
"set_issue_awaiting_deploy", "set_issue_deploying", "set_issue_monitoring",
"set_issue_approved",
):
monkeypatch.setattr(stage_engine, name, lambda *a, **k: None, raising=False)
yield
def _make_task(work_item_id, stage="analysis", repo="orchestrator", track="full"):
conn = get_db()
cur = conn.execute(
"INSERT INTO tasks (plane_id, work_item_id, repo, branch, stage, title, track) "
"VALUES (?, ?, ?, ?, ?, ?, ?)",
(work_item_id, work_item_id, repo, f"feature/{work_item_id}", stage, work_item_id, track),
)
tid = cur.lastrowid
conn.commit()
conn.close()
return tid
# --- TC-08: E2E walk, architecture skipped, every gate executed ------------
def test_tc08_bug_task_full_walk_skips_architecture(monkeypatch):
tid = _make_task("ORCH-e2e", stage="analysis", track="bug")
invoked = []
# Record + pass every registered edge gate. check_analysis_approved is NOT in
# this map: with finished_agent=None it is satisfied as approved-via-status
# (no call). check_architecture_done MUST never be invoked.
def _passing(name):
def _fn(*a, **k):
invoked.append(name)
return (True, f"{name} ok")
return _fn
for gate in (
"check_ci_green", "check_reviewer_verdict", "check_tests_passed",
"check_staging_status", "check_deploy_status", "check_architecture_done",
):
monkeypatch.setitem(stage_engine.QG_CHECKS, gate, _passing(gate))
visited = ["analysis"]
wi, repo, branch = "ORCH-e2e", "orchestrator", "feature/ORCH-e2e"
for _ in range(10):
row = db.get_task_by_work_item_id(wi)
cur = row["stage"]
if cur in ("done", "cancelled"):
break
res = advance_stage(tid, cur, repo, wi, branch, finished_agent=None)
if not res.advanced:
break
visited.append(res.to_stage)
assert "architecture" not in visited, f"bug task must skip architecture: {visited}"
assert visited[:3] == ["analysis", "development", "review"]
assert visited[-1] == "done", f"task should reach done: {visited}"
# Every downstream edge gate ran; the architecture gate never did.
for gate in ("check_ci_green", "check_reviewer_verdict", "check_tests_passed",
"check_staging_status", "check_deploy_status"):
assert gate in invoked, f"gate {gate} must execute on the bug track"
assert "check_architecture_done" not in invoked
# --- TC-09 / TC-10: start_pipeline classification --------------------------
async def _drive_start_pipeline(monkeypatch, *, is_bug: bool, enabled: bool):
from src.webhooks import plane
from src import plane_sync, bug_fast_track
from src.projects import ProjectConfig
monkeypatch.setattr(cfg.settings, "bug_fast_track_enabled", enabled, raising=False)
proj = ProjectConfig(
plane_project_id="proj-uuid", repo="orchestrator",
work_item_prefix="ORCH", name="orch",
)
monkeypatch.setattr(plane, "get_project_by_plane_id", lambda pid: proj)
monkeypatch.setattr(plane, "_qg0_errors", lambda name, desc: [])
monkeypatch.setattr(plane, "ensure_unique_work_item_id", lambda wid, repo: wid)
monkeypatch.setattr(plane_sync, "fetch_issue_sequence_id", lambda *a, **k: 777)
monkeypatch.setattr(plane_sync, "set_issue_analysis", lambda *a, **k: None)
monkeypatch.setattr(plane_sync, "add_comment", lambda *a, **k: None)
monkeypatch.setattr(plane, "enqueue_job", lambda *a, **k: 1)
async def _noop(*a, **k):
return None
monkeypatch.setattr(plane, "_create_gitea_branch", _noop)
monkeypatch.setattr(plane, "_create_initial_docs", _noop)
# Spy is_bug_task so we can assert it is/ isn't consulted; applies() stays REAL
# (flag + self-hosting scope), so TC-10 proves the local short-circuit.
seen = {"is_bug_task": 0}
def _is_bug(wi, pid=None):
seen["is_bug_task"] += 1
return is_bug
monkeypatch.setattr(bug_fast_track, "is_bug_task", _is_bug)
data = {
"id": "issue-uuid-1",
"name": "Fix the crash on submit",
"description_stripped": "A sufficiently long description for QG-0 to pass.",
"project": "proj-uuid",
}
await plane.start_pipeline(data, project_id="proj-uuid")
return seen
def test_tc09_bug_label_creates_bug_track(monkeypatch):
import asyncio
seen = asyncio.run(_drive_start_pipeline(monkeypatch, is_bug=True, enabled=True))
assert seen["is_bug_task"] == 1 # applies() True -> classification consulted
row = db.get_task_by_work_item_id("ORCH-777")
assert row is not None
assert row["track"] == "bug"
def test_tc09_no_label_creates_full_track(monkeypatch):
import asyncio
seen = asyncio.run(_drive_start_pipeline(monkeypatch, is_bug=False, enabled=True))
assert seen["is_bug_task"] == 1
row = db.get_task_by_work_item_id("ORCH-777")
assert row["track"] == "full"
def test_tc10_killswitch_off_bug_label_full_cycle(monkeypatch):
import asyncio
seen = asyncio.run(_drive_start_pipeline(monkeypatch, is_bug=True, enabled=False))
# applies() is False (kill-switch) -> is_bug_task short-circuited (zero network).
assert seen["is_bug_task"] == 0
row = db.get_task_by_work_item_id("ORCH-777")
assert row["track"] == "full"

View File

@@ -0,0 +1,105 @@
"""ORCH-019 — escalation of a complex bug to the full cycle (FR-5 / AC-5, D5).
Covers (04-test-plan.yaml):
TC-11 After the escalate endpoint resets track 'bug' -> 'full' (while the task
is still in `analysis`), the next advance routes analysis -> architecture
(return to the full cycle with the architect run).
"""
import os
import tempfile
import pytest
_test_db = os.path.join(tempfile.gettempdir(), "test_bug_fast_track_escalation.db")
os.environ["ORCH_DB_PATH"] = _test_db
os.environ["ORCH_REPOS_DIR"] = tempfile.gettempdir()
os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token")
os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token")
import src.db as db # noqa: E402
from src.db import init_db, get_db # noqa: E402
from src import stage_engine, config as cfg # noqa: E402
from src.stage_engine import advance_stage # noqa: E402
@pytest.fixture(autouse=True)
def fresh_db(monkeypatch, tmp_path):
dbfile = tmp_path / "esc.db"
monkeypatch.setattr(db.settings, "db_path", str(dbfile))
monkeypatch.setattr(cfg.settings, "bug_fast_track_enabled", True, raising=False)
init_db()
yield
@pytest.fixture(autouse=True)
def silence_side_effects(monkeypatch):
for name in (
"notify_stage_change", "notify_qg_failure", "notify_approve_requested",
"send_telegram", "plane_notify_stage", "plane_notify_qg", "plane_add_comment",
"set_issue_in_review", "set_issue_needs_input", "set_issue_in_progress",
"set_issue_blocked", "set_issue_done", "set_issue_analysis",
"set_issue_awaiting_deploy", "set_issue_deploying", "set_issue_monitoring",
"set_issue_approved",
):
monkeypatch.setattr(stage_engine, name, lambda *a, **k: None, raising=False)
yield
def _make_task(work_item_id, stage="analysis", track="bug"):
conn = get_db()
cur = conn.execute(
"INSERT INTO tasks (plane_id, work_item_id, repo, branch, stage, title, track) "
"VALUES (?, ?, ?, ?, ?, ?, ?)",
(work_item_id, work_item_id, "orchestrator", f"feature/{work_item_id}",
stage, work_item_id, track),
)
tid = cur.lastrowid
conn.commit()
conn.close()
return tid
def test_tc11_escalate_returns_to_full_cycle(monkeypatch):
import asyncio
from src import main
tid = _make_task("ORCH-cmplx", stage="analysis", track="bug")
# Operator escalates while the task is still in analysis.
out = asyncio.run(main.bug_fast_track_escalate(work_item="ORCH-cmplx"))
assert out["ok"] is True
assert out["track"] == "full"
assert out["was"] == "bug"
assert db.get_task_track(tid) == "full"
# The next advance now routes back through architecture (full cycle).
res = advance_stage(
tid, "analysis", "orchestrator", "ORCH-cmplx", "feature/ORCH-cmplx",
finished_agent=None,
)
assert res.to_stage == "architecture"
assert res.enqueued_agent == "architect"
def test_tc11_escalate_unknown_work_item():
import asyncio
from src import main
out = asyncio.run(main.bug_fast_track_escalate(work_item="ORCH-nope"))
assert out["ok"] is False
def test_tc11_escalate_missing_arg():
import asyncio
from src import main
out = asyncio.run(main.bug_fast_track_escalate(work_item=""))
assert out["ok"] is False
def test_tc11_escalate_idempotent_on_full(monkeypatch):
import asyncio
from src import main
tid = _make_task("ORCH-already", stage="analysis", track="full")
out = asyncio.run(main.bug_fast_track_escalate(work_item="ORCH-already"))
assert out["ok"] is True
assert out["was"] == "full"
assert db.get_task_track(tid) == "full"

View File

@@ -0,0 +1,97 @@
"""ORCH-019 — Quality-Gate invariants on the bug-fast-track (root invariant NFR-1).
Covers (04-test-plan.yaml):
TC-07 The QG_CHECKS registry + the check_* signatures are NOT changed by the
bug-fast-track; the machine verdict-keys (verdict / result / deploy_status /
staging_status / security_status / coverage_status) are preserved by name
and case.
TC-12 check_analysis_complete does NOT special-case the bug track (ADR-001 D4):
a bug lite-package that still emits all 4 analysis files passes; the same
requirement holds for a non-bug task (no false block, no weakening).
"""
import os
import tempfile
os.environ.setdefault(
"ORCH_DB_PATH", os.path.join(tempfile.gettempdir(), "test_bft_gates.db")
)
os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token")
os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token")
from src.qg.checks import QG_CHECKS, check_analysis_complete # noqa: E402
# --- TC-07: registry + verdict-keys unchanged ------------------------------
def test_tc07_qg_checks_registry_unchanged():
# The exact registered gate set — a bug-fast-track must add/remove NOTHING.
expected = {
"check_analysis_complete",
"check_analysis_approved",
"check_architecture_done",
"check_ci_green",
"check_review_approved",
"check_reviewer_verdict",
"check_tests_local",
"check_tests_passed",
"check_staging_status",
"check_staging_image_fresh",
"check_deploy_status",
"check_branch_mergeable",
"check_security_gate",
"check_coverage_gate",
}
assert set(QG_CHECKS.keys()) == expected
def test_tc07_verdict_keys_preserved():
"""The frontmatter machine verdict-keys are parsed by exact name/case. ORCH-019
touches none of the parsers, so the literal keys must still be present."""
import inspect
from src.qg import checks as checks_mod
src = inspect.getsource(checks_mod)
for key in ("verdict:", "result:", "deploy_status:", "staging_status:"):
assert key in src, f"verdict key '{key}' must be preserved in qg.checks"
# security_status / coverage_status live in their own leaves but are read via
# the same unified frontmatter contract — assert they survive there.
import inspect as _i
from src import security_gate, coverage_gate
assert "security_status" in _i.getsource(security_gate)
assert "coverage_status" in _i.getsource(coverage_gate)
# --- TC-12: analysis gate not weakened, no false block ---------------------
def _seed_analysis_docs(repo_root, work_item_id, files):
d = os.path.join(repo_root, "docs", "work-items", work_item_id)
os.makedirs(d, exist_ok=True)
for fn in files:
with open(os.path.join(d, fn), "w") as fh:
fh.write("stub\n")
def test_tc12_bug_lite_package_with_all_four_passes(monkeypatch, tmp_path):
from src.qg import checks as checks_mod
monkeypatch.setattr(checks_mod, "_repo_path", lambda repo, branch=None: str(tmp_path))
_seed_analysis_docs(
str(tmp_path), "ORCH-bug",
["01-brd.md", "02-trz.md", "03-acceptance-criteria.md", "04-test-plan.yaml"],
)
ok, reason = check_analysis_complete("orchestrator", "ORCH-bug", "feature/x")
assert ok is True, reason
def test_tc12_missing_file_still_fails_for_any_track(monkeypatch, tmp_path):
"""The gate is NOT weakened for bugs: a package missing 02/03 still fails —
exactly as for a non-bug task (the gate never reads tasks.track)."""
from src.qg import checks as checks_mod
monkeypatch.setattr(checks_mod, "_repo_path", lambda repo, branch=None: str(tmp_path))
_seed_analysis_docs(str(tmp_path), "ORCH-bug", ["01-brd.md", "04-test-plan.yaml"])
ok, reason = check_analysis_complete("orchestrator", "ORCH-bug", "feature/x")
assert ok is False
assert "02-trz.md" in reason and "03-acceptance-criteria.md" in reason
def test_tc12_signature_has_no_track_param():
import inspect
params = list(inspect.signature(check_analysis_complete).parameters)
# byte-for-byte signature: (repo, work_item_id, branch=None) — no track-awareness.
assert params == ["repo", "work_item_id", "branch"]

View File

@@ -0,0 +1,147 @@
"""ORCH-019 — advance_stage routing-override (ADR-001 D3).
Covers (04-test-plan.yaml):
TC-05 bug task: analysis -> development (architecture skipped, developer
enqueued); non-bug task: analysis -> architecture (architect enqueued).
TC-06 STAGE_TRANSITIONS is structurally unchanged (set of stages + edges +
agents + qg byte-for-byte) — the override does NOT mutate the table.
"""
import os
import tempfile
import pytest
_test_db = os.path.join(tempfile.gettempdir(), "test_bug_fast_track_routing.db")
os.environ["ORCH_DB_PATH"] = _test_db
os.environ["ORCH_REPOS_DIR"] = tempfile.gettempdir()
os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token")
os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token")
import src.db as db # noqa: E402
from src.db import init_db, get_db, set_task_track # noqa: E402
from src import stage_engine # noqa: E402
from src import config as cfg # noqa: E402
from src.stage_engine import advance_stage # noqa: E402
@pytest.fixture(autouse=True)
def fresh_db(monkeypatch, tmp_path):
dbfile = tmp_path / "r.db"
monkeypatch.setattr(db.settings, "db_path", str(dbfile))
monkeypatch.setattr(cfg.settings, "bug_fast_track_enabled", True, raising=False)
init_db()
yield
@pytest.fixture(autouse=True)
def silence_side_effects(monkeypatch):
for name in (
"notify_stage_change", "notify_qg_failure", "notify_approve_requested",
"send_telegram", "plane_notify_stage", "plane_notify_qg", "plane_add_comment",
"set_issue_in_review", "set_issue_needs_input", "set_issue_in_progress",
"set_issue_blocked", "set_issue_done", "set_issue_analysis",
"set_issue_awaiting_deploy", "set_issue_deploying", "set_issue_monitoring",
"set_issue_approved",
):
monkeypatch.setattr(stage_engine, name, lambda *a, **k: None, raising=False)
yield
def _make_task(work_item_id, stage="analysis", repo="orchestrator"):
conn = get_db()
cur = conn.execute(
"INSERT INTO tasks (plane_id, work_item_id, repo, branch, stage, title) "
"VALUES (?, ?, ?, ?, ?, ?)",
(work_item_id, work_item_id, repo, f"feature/{work_item_id}", stage, work_item_id),
)
tid = cur.lastrowid
conn.commit()
conn.close()
return tid
# --- TC-05 -----------------------------------------------------------------
def test_tc05_bug_task_skips_architecture():
tid = _make_task("ORCH-bug", stage="analysis")
set_task_track(tid, "bug")
# agent=None -> the webhook Approved-via-status path (gate satisfied, advance).
res = advance_stage(
tid, "analysis", "orchestrator", "ORCH-bug", "feature/ORCH-bug",
finished_agent=None,
)
assert res.advanced is True
assert res.to_stage == "development"
assert res.enqueued_agent == "developer"
# DB stage actually advanced past architecture.
row = db.get_task_by_work_item_id("ORCH-bug")
assert row["stage"] == "development"
def test_tc05_full_task_keeps_architecture():
tid = _make_task("ORCH-full", stage="analysis")
# track defaults to 'full' (no set_task_track call).
res = advance_stage(
tid, "analysis", "orchestrator", "ORCH-full", "feature/ORCH-full",
finished_agent=None,
)
assert res.advanced is True
assert res.to_stage == "architecture"
assert res.enqueued_agent == "architect"
def test_tc05_killswitch_off_bug_keeps_architecture(monkeypatch):
monkeypatch.setattr(cfg.settings, "bug_fast_track_enabled", False, raising=False)
tid = _make_task("ORCH-bugoff", stage="analysis")
set_task_track(tid, "bug") # stored, but the flag is off -> inert
res = advance_stage(
tid, "analysis", "orchestrator", "ORCH-bugoff", "feature/ORCH-bugoff",
finished_agent=None,
)
assert res.to_stage == "architecture"
assert res.enqueued_agent == "architect"
def test_tc05_bug_only_affects_analysis_edge():
"""The override is scoped to the analysis-exit edge only — a bug task on
`development` still routes development -> review (no spurious skips)."""
tid = _make_task("ORCH-bugdev", stage="development")
set_task_track(tid, "bug")
# Make check_ci_green pass deterministically (we only assert routing, not CI).
import src.stage_engine as se
orig = se.QG_CHECKS.get("check_ci_green")
se.QG_CHECKS["check_ci_green"] = lambda *a, **k: (True, "ok")
try:
res = advance_stage(
tid, "development", "orchestrator", "ORCH-bugdev", "feature/ORCH-bugdev",
finished_agent=None,
)
finally:
if orig is not None:
se.QG_CHECKS["check_ci_green"] = orig
assert res.to_stage == "review"
# --- TC-06: STAGE_TRANSITIONS structurally unchanged -----------------------
def test_tc06_stage_transitions_unchanged():
from src.stages import STAGE_TRANSITIONS
expected = {
"created": {"next": "analysis", "agent": "analyst", "qg": None},
"analysis": {"next": "architecture", "agent": "architect", "qg": "check_analysis_approved"},
"architecture": {"next": "development", "agent": "developer", "qg": "check_architecture_done"},
"development": {"next": "review", "agent": "reviewer", "qg": "check_ci_green"},
"review": {"next": "testing", "agent": "tester", "qg": "check_reviewer_verdict"},
"testing": {"next": "deploy-staging", "agent": "deployer", "qg": "check_tests_passed"},
"deploy-staging": {"next": "deploy", "agent": "deployer", "qg": "check_staging_status"},
"deploy": {"next": "done", "agent": None, "qg": "check_deploy_status"},
"done": {"next": None, "agent": None, "qg": None},
"cancelled": {"next": None, "agent": None, "qg": None},
}
assert STAGE_TRANSITIONS == expected
def test_tc06_get_next_stage_pure():
"""get_next_stage / get_agent_for_stage stay PURE (no track arg) — the override
lives in advance_stage, not in stages.py."""
from src.stages import get_next_stage, get_agent_for_stage
assert get_next_stage("analysis") == "architecture"
assert get_agent_for_stage("analysis") == "architect"

View File

@@ -0,0 +1,79 @@
"""ORCH-019 (TC-15) — additive, idempotent tasks.track migration.
The bug-fast-track stores the task type in an additive ``tasks.track`` column
(``TEXT DEFAULT 'full'``) created via ``_ensure_column`` (idempotent). A repeated
``init_db`` must not crash, existing rows must default to ``'full'``, and the
helpers must round-trip.
"""
import os
import tempfile
import pytest
os.environ.setdefault(
"ORCH_DB_PATH", os.path.join(tempfile.gettempdir(), "test_db_migrations.db")
)
os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token")
os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token")
import src.db as db # noqa: E402
from src.db import init_db, get_db, set_task_track, get_task_track # noqa: E402
@pytest.fixture(autouse=True)
def fresh_db(tmp_path, monkeypatch):
dbfile = tmp_path / "m.db"
monkeypatch.setattr(db.settings, "db_path", str(dbfile))
init_db()
yield
def _columns(table):
conn = get_db()
try:
return [r[1] for r in conn.execute(f"PRAGMA table_info({table})").fetchall()]
finally:
conn.close()
def test_tc15_track_column_present_with_default():
assert "track" in _columns("tasks")
# A row inserted WITHOUT track gets the DEFAULT 'full'.
conn = get_db()
conn.execute(
"INSERT INTO tasks (plane_id, work_item_id, repo, branch, stage, title) "
"VALUES ('p','ORCH-1','orchestrator','feature/x','analysis','t')"
)
conn.commit()
row = conn.execute("SELECT track FROM tasks WHERE work_item_id='ORCH-1'").fetchone()
conn.close()
assert row["track"] == "full"
def test_tc15_init_db_idempotent():
# Running init_db again is a no-op on the existing column (no crash).
init_db()
init_db()
assert "track" in _columns("tasks")
def test_tc15_helpers_round_trip():
conn = get_db()
cur = conn.execute(
"INSERT INTO tasks (plane_id, work_item_id, repo, branch, stage, title) "
"VALUES ('p2','ORCH-2','orchestrator','feature/y','analysis','t')"
)
tid = cur.lastrowid
conn.commit()
conn.close()
assert get_task_track(tid) == "full" # default
set_task_track(tid, "bug")
assert get_task_track(tid) == "bug"
set_task_track(tid, "full")
assert get_task_track(tid) == "full"
def test_tc15_get_task_track_missing_row_failsafe():
# Unknown task id -> 'full' (fail-safe -> full cycle), never raises.
assert get_task_track(999999) == "full"

View File

@@ -59,3 +59,50 @@ def test_queue_serial_gate_reflects_freeze():
assert "orchestrator" in per
assert per["orchestrator"]["frozen"] is True
assert per["orchestrator"]["frozen_reason"] == "DEGRADED"
# --- ORCH-019 (TC-13): additive bug_fast_track block -----------------------
def test_queue_has_bug_fast_track_block_and_keeps_existing_keys(monkeypatch):
import asyncio
from src import main
monkeypatch.setattr(cfg.settings, "bug_fast_track_enabled", True, raising=False)
payload = asyncio.run(main.queue())
# Pre-existing keys are all still present (no contract break).
for key in ("counts", "serial_gate", "coverage", "auto_labels", "stop", "recent"):
assert key in payload, f"existing /queue key '{key}' must be preserved"
assert "bug_fast_track" in payload
bft = payload["bug_fast_track"]
assert bft["enabled"] is True
assert set(bft) >= {
"enabled", "label", "repos",
"active_bug_tasks", "total_bug_tasks", "est_saved_architecture_runs",
}
def test_queue_bug_fast_track_counts_bug_tasks():
import asyncio
from src import main
conn = db.get_db()
conn.execute(
"INSERT INTO tasks (plane_id, work_item_id, repo, branch, stage, title, track) "
"VALUES ('p1','ORCH-401','orchestrator','feature/x','development','t','bug')"
)
conn.execute(
"INSERT INTO tasks (plane_id, work_item_id, repo, branch, stage, title, track) "
"VALUES ('p2','ORCH-402','orchestrator','feature/y','done','t','bug')"
)
conn.execute(
"INSERT INTO tasks (plane_id, work_item_id, repo, branch, stage, title, track) "
"VALUES ('p3','ORCH-403','orchestrator','feature/z','development','t','full')"
)
conn.commit()
conn.close()
bft = asyncio.run(main.queue())["bug_fast_track"]
assert bft["total_bug_tasks"] == 2 # two bug tasks total
assert bft["active_bug_tasks"] == 1 # one non-terminal bug task
assert bft["est_saved_architecture_runs"] == 2