--- work_item: ORCH-118 stage: analysis author_agent: analyst status: ready-for-review created_at: 2026-06-15 model_used: claude-opus-4-8 --- # 01 — BRD (бизнес-требования): ORCH-118 — replace avoidable LLM control paths with deterministic implementations Work Item: **ORCH-118** · Repo: **orchestrator** · Стадия: analysis > ⚠️ **Inventory-first.** Это **зонтичная inventory/architecture-задача**, а НЕ реализация > детерминированных раннеров. Её результат — **карта** всех мест вызова LLM + классификация + > упорядоченный roadmap + нормативная политика использования LLM, защищённая структурными тестами. > Реализация конкретных замен — **последующие задачи**, запускаемые ПОСЛЕ утверждения карты. Их код > в ORCH-118 **не вносится** (см. §2 «Вне объёма»). > 📌 **Follow-up'ы именуются по РОЛИ, без выдуманных Plane-ID.** Roadmap рекомендует отдельные > follow-up задачи по ролям-кандидатам (**deployer-замена**, **tester-гибрид** и т.д.). Конкретные > Plane-ID этих задач в артефактах ORCH-118 **НЕ фиксируются** — они присваиваются при фактическом > заведении задач в backlog. Аналитик не имеет доказательного источника на конкретные ID и не должен > их выдумывать (см. NFR-6). > 🔁 **Revision R3 (2026-06-15).** Из пакета **удалена** нормативная привязка follow-up'ов к > конкретным ID `ORCH-115`/`ORCH-116` (этих work item нет ни в репозитории, ни в подтверждённом > backlog — claim «источник истины: live Plane backlog» был **непроверяемым**). Вместе с ней удалены > навязывавший её структурный тест (бывш. TC-11) и отдельный критерий приёмки (бывш. AC-9). Follow-up'ы > теперь описаны **по роли**, ID — TBD. Содержательная классификация ролей не менялась > (deployer = кандидат на детерминированную замену, tester = кандидат на hybrid-fallback). > *(R1→R2 ранее «чинил» порядок этих ID; R3 убирает корень проблемы — фиксацию несуществующих ID.)* --- ## 1. Бизнес-контекст и проблема Зонтичный follow-up по итогам RCA-цепочки **ORCH-114/117** (и предшествующих ORCH-110/111/112/113): корневым классом инцидентов было то, что **side-effectful и решающие control-path'ы не имели единого детерминированного владения** — где-то решение принималось «потому что так удобно» через LLM-агента, хотя по сути это исполнение фиксированных команд и маппинг результата. Установленный факт по текущему коду (инвентаризация — §1 TRZ, артефакт-карта): - В оркестраторе **ровно одна точка запуска LLM** — `src/agents/launcher.py::_spawn` (одна `subprocess.Popen` сборка Claude CLI: `CLAUDE_BIN --print … --system-prompt "$(cat …)"`), которой пользуются **6 ролей-агентов** (analyst, architect, developer, reviewer, tester, deployer). - **Все остальные control-path'ы уже детерминированы (без LLM):** маршрутизация стадий (`STAGE_TRANSITIONS`/`advance_stage`), все Quality Gate'ы и под-гейты (`check_*`, security/merge/ coverage/image-freshness), парсеры вердиктов (`_parse_*` через `frontmatter.py`), классификатор ретраев (`error_classifier.py`), serial-gate/transition-lease/reconciler/reaper, а также **две зарезервированные job-роли** `deploy-finalizer` и `post-deploy-monitor` (перехватываются в `launch_job` **до** `_spawn` — это рабочий прецедент детерминированной замены агента). - Среди 6 LLM-ролей **tester** и **deployer** по факту почти полностью исполняют детерминированные команды (`pytest`, `staging_check.py`, exit-code → вердикт; прод-деплой на self-hosting уже идёт детерминированным путём Phase A/B/C, ORCH-036), завёрнутые в LLM «для удобства». Боль/риск, который закрывает задача: LLM на механических путях — это (а) лишний источник недетерминизма и инцидентов (ложный вердикт/действие), (б) задержка (запуск opus-агента вместо прямого вызова), (в) расход токенов/денег. При этом «вслепую» убирать LLM нельзя — часть путей несёт **настоящее суждение** (анализ, архитектура, написание кода, ревью), и автономность/гибкость должны сохраниться. ORCH-118 даёт **доказательную карту** «где LLM действительно нужен, а где это удобство» и **упорядоченный план** безопасных замен — фундамент, на котором последующие срезы (по ролям-кандидатам) выполняются предсказуемо и без регресса. ## 2. Объём (scope) ### В объёме - **BR-1** Полная инвентаризация всех мест вызова LLM и всех ролей-агентов (карта call-site'ов). - **BR-2** Классификация каждого call-site в один из 4 классов (keep / replace-now / replace-later / hybrid-fallback) с явным обоснованием. - **BR-3** Доказательное подтверждение (с привязкой `file:line`), что не-агентские control-path'ы (маршрутизация / ретраи / QG / парсеры / finalizer'ы) уже детерминированы. - **BR-4** Упорядоченный roadmap замен: зависимости, оценка экономии токенов/времени, риски безопасности, потребность в hybrid-fallback, рекомендованный **первый срез** — кандидаты названы **по роли** (follow-up ID — TBD). - **BR-5** Нормативная **политика использования LLM** («LLM — только там, где нужно настоящее суждение») как durable-документ. - **BR-6** Структурные regression-тесты, **прибивающие инварианты карты к коду** (единственная точка запуска; детерминированные модули не несут запуска LLM; карта покрывает все промпты; тотальность классификации) — анти-дрейф. - **BR-7** Явно позиционировать **роль deployer** и **роль tester** как **кандидаты-follow-up** для детерминированной замены — **по роли, без привязки к конкретным Plane-ID** (см. NFR-6). ### Вне объёма - ❌ **Реализация** детерминированных раннеров deployer / tester и любых других замен — это отдельные follow-up задачи ПОСЛЕ утверждения карты (явное требование заказчика в business request). - ❌ **Выдумывание/фиксация конкретных follow-up Plane-ID** (напр. `ORCH-115`/`ORCH-116`) в любых артефактах ORCH-118 — ID присваиваются при заведении задач (NFR-6). - ❌ Изменение `STAGE_TRANSITIONS` / реестра `QG_CHECKS` / семантики и имён `check_*` / machine-verdict-ключей (`verdict:`/`result:`/`staging_status:`/`deploy_status:`/`security_status:`/ `coverage_status:`) / схемы БД. - ❌ Включение model-routing (G3 ORCH-41) или смена модели/эффорта ролей. - ❌ Любая правка поведения `src/**` в рантайме (ORCH-118 — **docs + tests only**, по образцу ORCH-077/079/101/102/103/011). - ❌ Снижение автономности или гибкости конвейера. ## 3. Заинтересованные стороны - **Заказчик / Owner** — инициатор RCA-трека ORCH-114/117; принимает карту и roadmap (gate утверждения). - **Сопровождающие платформы (self-hosting)** — выигрывают в стабильности, скорости, экономии токенов. - **Downstream-проекты (enduro-trails)** — делят общий прод/очередь; для них требуется **нулевая регрессия** (NFR-1). - **Будущие исполнители follow-up'ов** — потребители карты, roadmap и политики. ## 4. Бизнес-требования (BR) - **BR-1 — Инвентарь call-site'ов LLM.** Выпустить durable-документ, перечисляющий **каждое** место, где LLM вызывается или может быть вызван: единственную точку `_spawn`, все 6 ролей-агентов и обе зарезервированные детерминированные job-роли (как доказательство «уже без LLM»). Для каждого — `file:line`, триггер, стадия/владелец, выходной артефакт, machine-verdict-ключ (если есть), оценка токенов/времени. Проверяемо: каждый `file:line` резолвится в реальный код. - **BR-2 — Классификация.** Каждому call-site присвоить **ровно один** класс из таксономии: `keep-LLM` (нужно настоящее суждение), `replace-deterministic-now` (безопасная замена сейчас), `replace-later/risky` (замена позже / рискованно), `needs-hybrid-fallback` (детерминированное ядро + LLM-фолбэк на суждение). Для `keep-LLM` — **назвать конкретное суждение**, ради которого LLM сохраняется. - **BR-3 — Подтверждение детерминизма не-агентских путей.** Документально, с `file:line`-доказательством, зафиксировать, что маршрутизация стадий, ретраи, QG-проверки, парсеры вердиктов и finalizer'ы **не вызывают LLM**. Если инвентаризация найдёт неожиданный LLM-путь — он попадает в карту и классификацию. - **BR-4 — Упорядоченный roadmap.** Ранжированный план замен: для каждого кандидата (названного **по роли**) — зависимости, **оценка** экономии токенов/времени (из телеметрии `agent_runs`), риск безопасности, нужен ли hybrid-fallback, ожидание kill-switch/обратимости. Явно указать **рекомендованный первый срез** и обоснование выбора. Привязка к follow-up задаче — **по роли**; конкретный Plane-ID НЕ фиксируется (заводится отдельно, NFR-6). - **BR-5 — Политика использования LLM.** Нормативный durable-документ: «LLM — только там, где требуется настоящее суждение»; критерии решения keep vs replace; требование к новым/изменённым control-path'ам обосновывать любое использование LLM против этой политики. - **BR-6 — Анти-дрейф структурными тестами.** Тесты, привязывающие инварианты карты к коду: единственная точка запуска LLM; перечисленные детерминированные модули/job-роли не несут запуска; карта перечисляет ровно те 6 промптов, что лежат в `.openclaw/agents/`; классификация покрывает все call-site'ы по одному разу. Тесты — offline (без сети/LLM/subprocess-к-модели). **Тест на привязку к конкретным follow-up ID не вводится** (анти-паттерн: прибивал бы карту к непроверяемым ID, R3). - **BR-7 — Позиционирование follow-up'ов по роли.** Карта/roadmap явно отмечают **роль deployer** и **роль tester** как кандидаты-замены, **не** реализуемые в ORCH-118; их старт гейтится утверждением карты. Привязка — **по роли**, без конкретных Plane-ID (NFR-6). ## 5. Нефункциональные требования (NFR) - **NFR-1 — Сохранение поведения (нулевая регрессия).** ORCH-118 — docs+tests only: `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict-ключи/схема БД — **байт-в-байт**; поведение конвейера 1:1; enduro-trails не затронут. - **NFR-2 — Сохранение автономности и гибкости.** Ни инвентаризация, ни политика не должны предлагать решений, снижающих автономный/пакетный режим (ORCH-088/089) или гибкость; политика **защищает** автономность как инвариант любой будущей замены. - **NFR-3 — Self-hosting безопасность.** Задача только **читает** код и пишет docs+tests — не деплоит, не рестартит прод-контейнер, не трогает `main`/force-push, не запускает процессов/сети. - **NFR-4 — Трассируемость и сопровождаемость.** Карта привязана к коду маркерами/тестом и остаётся честной при эволюции кода; формат — по `docs/_standards/PIPELINE_DOCS.md` и `TRACEABILITY.md`. - **NFR-5 — Доказательность экономии.** Цифры экономии берутся из реальной телеметрии `agent_runs` (модель/эффорт/токены/стоимость/время по ролям) и помечаются как **оценки** до фактического замера после реализации. - **NFR-6 — Только проверяемые ссылки (анти-фабрикация, R3).** В артефактах фиксируются только ссылки, резолвящиеся в код/документы репозитория. Конкретные **follow-up Plane-ID не выдумываются**: кандидаты-замены именуются по роли; ID присваивается при заведении задачи. (Это закрывает корень отклонённой ревизии R2.) ## 6. Допущения и ограничения - Единственный транспорт LLM сейчас — Claude CLI через `launcher._spawn`; прямых вызовов Anthropic API в `src/**` нет (подтверждается инвентаризацией). - Model-routing не включён — все 6 ролей на `claude-opus-4-8` (ORCH-41), что упрощает оценку экономии. - Карта — **снимок на момент задачи**, защищённый структурными тестами от тихого расхождения с кодом. - Прецедент детерминированной замены агента уже существует и работает (`deploy-finalizer`/ `post-deploy-monitor` в `launch_job` до `_spawn`) — это снижает архитектурный риск follow-up'ов. - На момент анализа конкретные follow-up work item для замены ролей в backlog **не подтверждены** — поэтому ID не фиксируются (NFR-6). ## 7. Критерии успеха Карта call-site'ов полна и привязана к коду; каждый site классифицирован с обоснованием; детерминизм не-агентских путей доказан; есть упорядоченный roadmap с зависимостями/экономией/рисками и рекомендованным первым срезом (кандидаты — по роли); есть нормативная политика; структурные тесты зелёные и осмысленные; ни один рантайм-инвариант не тронут; раннеры замен НЕ реализованы; ни один артефакт не фиксирует непроверяемых follow-up ID. Детальные PASS/FAIL — в `03-acceptance-criteria.md`. ## 8. Риски - **Недо-/пере-классификация** (LLM убран там, где нужно суждение, или сохранён там, где не нужен) → митигирует требование «назвать конкретное суждение» для `keep-LLM` и ревью карты. - **Дрейф карты** относительно кода со временем → митигируют структурные тесты (BR-6). - **Преждевременная замена** в погоне за экономией ценой автономности/гибкости → инвентаризация отделена от реализации; первый срез — самый низкорисковый. - **Фабрикация ссылок/ID** (рецидив дефекта R2) → митигирует NFR-6 (только проверяемые ссылки; follow-up'ы — по роли) и ревью. Детали техн.рисков — `10-tech-risks.md` (архитектор).