---
work_item: ORCH-118
stage: architecture
author_agent: architect
status: accepted
created_at: 2026-06-15
model_used: claude-opus-4-8
---

# adr-0047: Нормативная политика использования LLM + карта call-site'ов (control-path-ось «avoidable»)

> **Сквозной (cross-cutting) ADR.** Агрегирует решение ORCH-118, влияющее на **весь** оркестратор:
> нормативная политика использования LLM, три ортогональных оси, определение «avoidable LLM control
> path» и снимок-карта LLM-консультаций, прибитая к коду структурными тестами. Локальная детализация —
> `docs/work-items/ORCH-118/06-adr/ADR-001-llm-call-site-map-and-determinization-roadmap.md`.

## Статус
Accepted

## Контекст

RCA-цепочка ORCH-114/117 (и 110/111/112/113) показала корневой класс: у side-effectful и решающих
control-path'ов не было единого детерминированного владения; местами решение брал LLM-агент «потому
что удобно», хотя по сути это исполнение фиксированных команд + маппинг результата — лишний
недетерминизм, задержка и расход токенов в точке ветвления.

Оркестратор не имел **нормативного критерия** «где LLM нужен, а где это avoidable control path» и
**карты** мест вызова LLM, прибитой к коду. Без них любая будущая правка control-path'а могла снова
ввести LLM «на удобстве», а «вслепую» убирать LLM нельзя — часть путей несёт настоящее суждение
(анализ, архитектура, написание кода, ревью).

**Ground-truth кода (ORCH-118, сверено):** единственный транспорт LLM-консультации в `src/**` —
`launcher._spawn` (`launcher.py:472`, CLI `610-614`); иного LLM-транспорта нет (нет SDK-импортов /
прямого HTTP Anthropic / второго сборщика). 6 ролей-агентов консультируют через него; D1/D2
(`deploy-finalizer`/`post-deploy-monitor`) перехватываются в `launch_job` **до** `_spawn`
(`launcher.py:389/394`) — слот есть, консультации нет. Потребитель вывода каждой роли — конкретный
`check_*`/`_parse_*` в `src/qg/checks.py`.

## Решение

### D1 — Три ортогональных оси (нормативно для всего оркестратора)

1. **consultation ≠ transport/slot** — «потребляет суждение LLM» ≠ «спавнит процесс / занимает слот
   агента» (capability ≠ consultation).
2. **control-path (C) ≠ artifact-producer (P)** — определяется кодом-потребителем: C — `check_*`
   ветвится на machine-verdict, написанном LLM; P — детерминированный гейт судит артефакт независимо
   (файлы/CI).
3. **деривируемость вердикта** — вердикт C-консультации либо детерминированная функция tool-сигналов
   (exit-code `pytest`/smoke/`staging_check.py`/деплоя), либо настоящее суждение.

### D2 — Нормативное определение «avoidable LLM control path»

> Call-site — **avoidable LLM control path** ⟺ **(i)** C-консультация (LLM-вердикт потребляется
> потоком управления) **И (ii)** вердикт деривируем из tool-сигналов, которые оркестратор уже
> вычисляет → LLM не добавляет информации.

Целевой набор (доказательно из `src/qg/checks.py`): **avoidable = {tester, deployer}**;
control-path-но-keep = `{reviewer}`; не-control-path (P, keep) = `{analyst, architect, developer}`;
уже детерминированы (вне консультаций) = `{deploy-finalizer, post-deploy-monitor}`.

### D3 — Нормативная политика использования LLM (`docs/architecture/llm-usage-policy.md`)

Принцип: **«LLM — только там, где требуется настоящее суждение».** Критерий keep vs replace —
через оси D1 (является ли путь control path; деривируем ли вердикт; обратимость; влияние на
автономность NFR-2). **Требование:** любая новая/изменённая control-path-консультация обязана
обосновать использование LLM против этой политики; reviewer контролирует это как обзорную ось
(в духе ORCH-079) — **как требование, не как новый машинный гейт**.

### D4 — Карта как снимок, прибитый к коду

`docs/architecture/llm-call-sites.md` — инвентарь + control-path-разметка + классификация со
схемой полей и машинным блоком (детали — work-item ADR-001 D2/D4). Структурные тесты
`tests/test_llm_call_site_inventory.py` (offline) держат инварианты: транспорт-агностичный
двусторонний инвариант единственной точки, отсутствие консультации в детерминированных путях,
control-path-разметка сверена с `src/qg/checks.py`, avoidable-набор = `{tester, deployer}`.

### D5 — Roadmap детерминизации (`docs/architecture/llm-determinization-roadmap.md`)

Рекомендованный первый срез — **deployer (staging-status)** (`replace-deterministic-now`: чистый
маппинг exit-кода `staging_check.py`; прод уже детерминирован Phase A/B/C ORCH-036; опора на
прецедент D1/D2). Затем — **tester-гибрид** (`needs-hybrid-fallback`). Кандидаты — **по роли**,
без конкретных Plane-ID (NFR-6).

### D6 — Скоуп и инварианты (нормативно)

ORCH-118 — **docs + tests only**: `STAGE_TRANSITIONS` / реестр и имена `QG_CHECKS`/`check_*` /
machine-verdict-ключи / схема БД — **байт-в-байт не тронуты**; раннеры замен не реализуются;
follow-up Plane-ID не фиксируются. Self-hosting-безопасно (только чтение кода + запись docs/tests).

**Норматив сопровождения (durable):** менял места вызова LLM **или** потребителя вердикта в
`src/qg/checks.py` → обнови карту/разметку и политику в **том же PR** (иначе тесты D4 красные).

## Альтернативы
- **Машинный гейт-enforcement политики (новый QG)** — отвергнуто: политика нормативно-описательная,
  как ось трассировки ORCH-078; новый QG увеличил бы поверхность риска без необходимости (FR-6 §QG).
- **Реализация раннеров в этой же задаче** — отвергнуто: inventory-first по требованию заказчика;
  «вслепую» убирать LLM рискованно без утверждённой карты.
- **Привязка к конкретным follow-up ID** — отвергнуто (NFR-6, корень отклонённой R2).

## Последствия
- **+** Единый нормативный критерий и код-привязанная карта закрывают класс «LLM на удобстве» и
  делают замены предсказуемыми; автономность защищена политикой.
- **−** Карта — снимок: эволюция `src/qg/checks.py` требует со-обновления карты (держится тестами).
  *Митигейшн:* запланированный норматив сопровождения, тест указывает точку дрейфа.
- **Откат:** удаление/правка `docs/architecture/llm-*.md` + тест-файла + секции README; рантайм не
  затронут.

## Ссылки
- Work-item ADR: `docs/work-items/ORCH-118/06-adr/ADR-001-llm-call-site-map-and-determinization-roadmap.md`
- BRD/TRZ/AC: `docs/work-items/ORCH-118/{01-brd,02-trz,03-acceptance-criteria}.md`
- Сверено по коду: `src/agents/launcher.py`, `src/qg/checks.py`, `.openclaw/agents/*.md`
- Связанные: ORCH-036 (детерминированный self-deploy), ORCH-061 (`staging_verdict`),
  ORCH-077/079 (docs/prompts-only прецедент + reviewer-ось обзорных доков), ORCH-114/117 (RCA-трек)
</content>
