185 lines
20 KiB
Markdown
185 lines
20 KiB
Markdown
---
|
||
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` (архитектор).
|