orchestrator/docs/work-items/ORCH-118/01-brd.md

work_item, stage, author_agent, status, created_at, model_used

work_item	stage	author_agent	status	created_at	model_used
ORCH-118	analysis	analyst	ready-for-review	2026-06-15	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, защищённая структурными тестами. Реализация конкретных замен (tester — ORCH-115, deployer — ORCH-116 и др.) — последующие задачи, запускаемые ПОСЛЕ утверждения карты. Их код в ORCH-118 не вносится (см. §2 «Вне объёма»).

---

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), которой пользуются 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 действительно нужен, а где это удобство» и упорядоченный план безопасных замен — фундамент, на котором ORCH-115/116 (и возможные следующие срезы) выполняются предсказуемо и без регресса.

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, рекомендованный первый срез.
• BR-5 Нормативная политика использования LLM («LLM — только там, где нужно настоящее суждение») как durable-документ.
• BR-6 Структурные regression-тесты, прибивающие инварианты карты к коду (единственная точка запуска; детерминированные модули не несут запуска LLM; карта покрывает все промпты) — анти-дрейф.
• BR-7 Явно позиционировать ORCH-115 (tester) и ORCH-116 (deployer) как кандидаты-follow-up.

Вне объёма

• ❌ Реализация детерминированных раннеров tester/deployer (ORCH-115/116) и любых других замен — это отдельные задачи ПОСЛЕ утверждения карты (явное требование заказчика в business request).
• ❌ Изменение 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).
• Будущие исполнители ORCH-115/116/… — потребители карты, 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 work item. Явно указать рекомендованный первый срез и обоснование выбора.
• BR-5 — Политика использования LLM. Нормативный durable-документ: «LLM — только там, где требуется настоящее суждение»; критерии решения keep vs replace; требование к новым/изменённым control-path'ам обосновывать любое использование LLM против этой политики.
• BR-6 — Анти-дрейф структурными тестами. Тесты, привязывающие инварианты карты к коду: единственная точка запуска LLM; перечисленные детерминированные модули/job-роли не несут запуска; карта перечисляет ровно те 6 промптов, что лежат в .openclaw/agents/; классификация покрывает все call-site'ы по одному разу. Тесты — offline (без сети/LLM/subprocess-к-модели).
• BR-7 — Позиционирование follow-up'ов. Карта/roadmap явно отмечают ORCH-115 (tester) и ORCH-116 (deployer) как кандидаты-замены, не реализуемые в ORCH-118; их старт гейтится утверждением карты.

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 (модель/эффорт/токены/стоимость/время по ролям) и помечаются как оценки до фактического замера после реализации.

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'ов.

7. Критерии успеха

Карта call-site'ов полна и привязана к коду; каждый site классифицирован с обоснованием; детерминизм не-агентских путей доказан; есть упорядоченный roadmap с зависимостями/экономией/рисками и рекомендованным первым срезом; есть нормативная политика; структурные тесты зелёные и осмысленные; ни один рантайм-инвариант не тронут; ORCH-115/116 НЕ реализованы. Детальные PASS/FAIL — в 03-acceptance-criteria.md.

8. Риски

• Недо-/пере-классификация (LLM убран там, где нужно суждение, или сохранён там, где не нужен) → митигирует требование «назвать конкретное суждение» для keep-LLM и ревью карты.
• Дрейф карты относительно кода со временем → митигируют структурные тесты (BR-6).
• Преждевременная замена в погоне за экономией ценой автономности/гибкости → инвентаризация отделена от реализации; первый срез — самый низкорисковый. Детали — 10-tech-risks.md (архитектор).