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, защищённая структурными тестами. Реализация конкретных замен — последующие задачи, запускаемые ПОСЛЕ утверждения карты. Их код в 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 (архитектор).