claude-bot
9710d5f80d
ORCH-118 (inventory-first, docs+tests only): publish an evidence-based map of
every place the orchestrator's control flow consumes (or can consume) an LLM
judgment, mark the control-path axis (C control-path vs P artifact-producer),
define "avoidable LLM control path" as a checkable two-bit predicate, classify
each call-site, and order the deterministic-replacement roadmap. Pin the map to
code with offline structural anti-drift tests.
- docs/architecture/llm-call-sites.md — map + machine-readable inventory block
+ control-path axis + classification + keep-LLM justifications + deterministic
non-agent paths (FR-1/FR-2/FR-3/FR-8).
- docs/architecture/llm-determinization-roadmap.md — ordered candidates BY ROLE,
savings sourced from agent_runs, recommended first slice = deployer staging
(FR-4). No fabricated follow-up Plane-IDs (R3/NFR-6).
- docs/architecture/llm-usage-policy.md — normative principle, keep/replace
criteria via the axis, definition of "avoidable LLM control path" (FR-5/FR-8).
- tests/test_llm_call_site_inventory.py — TC-01/02/03/04/05/06/09/12/13/14.
- tests/test_llm_determinization_docs.py — TC-07/08/11.
- CHANGELOG.md + docs/overview/tech-quality-security.md — golden-source sync (AC-8).
Avoidable LLM control paths = {tester, deployer}; control-path-keep = {reviewer};
not-control-path (P) = {analyst, architect, developer}. Single LLM transport =
launcher._spawn (S0); no alternative transport (TC-12). Runtime untouched:
STAGE_TRANSITIONS / QG_CHECKS / check_* / machine-verdict keys / DB schema are
byte-for-byte; no replacement runners implemented (FR-7). Full suite: 2081 passed.
Refs: ORCH-118
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
97 lines
8.5 KiB
Markdown
97 lines
8.5 KiB
Markdown
# LLM usage policy (ORCH-118)
|
||
|
||
> **Нормативный durable-документ.** Формулирует принцип использования LLM в оркестраторе, критерии
|
||
> «keep vs replace» через **control-path-ось**, и нормативное **определение «avoidable LLM control
|
||
> path»**. Применяется ко **всем** будущим правкам control-path'ов. Сопутствующие артефакты —
|
||
> карта [`llm-call-sites.md`](llm-call-sites.md) и roadmap [`llm-determinization-roadmap.md`](llm-determinization-roadmap.md).
|
||
|
||
---
|
||
|
||
## 1. Принцип
|
||
|
||
**LLM — только там, где нужно настоящее суждение.** Если решение/вердикт control-path'а есть
|
||
**детерминированная функция tool-сигналов**, которые оркестратор уже вычисляет (exit-code `pytest`,
|
||
smoke, `staging_check.py`, статус деплоя, наличие файлов, CI-статус), — оно должно приниматься
|
||
**детерминированно**, а не консультацией LLM. LLM сохраняется там, где требуется суждение, **не
|
||
сводимое** к tool-сигналу (анализ требований, архитектурное решение, написание кода, приемлемость
|
||
ревью).
|
||
|
||
Это защищает **автономность** (NFR-2): меньше точек, где недетерминизм/стоимость/латентность LLM
|
||
встроены в поток управления, и меньше класса инцидентов «LLM-агент принял решение, которое на деле
|
||
есть исполнение фиксированных команд и маппинг результата» (RCA-трек ORCH-110/111/112/113/114/117).
|
||
|
||
---
|
||
|
||
## 2. Три оси решения (ground-truth — код)
|
||
|
||
1. **consultation ≠ transport/slot.** «LLM консультируется» ⇔ решение/артефакт конвейера **потребляет
|
||
суждение LLM**. Существование транспорта (`_spawn`) или слота агента (job-роли с перехватом до
|
||
`_spawn`) — это **capability**, не консультация.
|
||
2. **control-path (C) ≠ artifact-producer (P)** — определяется **кодом-потребителем** вывода роли:
|
||
- **(C)** LLM эмитит machine-verdict, на котором **ветвится `check_*`-гейт** → суждение входит в
|
||
поток управления.
|
||
- **(P)** LLM производит артефакт, а продвижение решает **детерминированный гейт** независимо
|
||
(наличие файлов / CI) → суждение в control flow не входит.
|
||
3. **деривируемость вердикта** — вердикт C-консультации либо детерминированная функция tool-сигналов,
|
||
либо настоящее суждение, не сводимое к exit-коду.
|
||
|
||
---
|
||
|
||
## 3. Нормативное определение «avoidable LLM control path»
|
||
|
||
Это **двухбитный проверяемый предикат над `src/qg/checks.py`**, а не «удобство на глаз».
|
||
|
||
<!-- ORCH-118-AVOIDABLE-DEFINITION-BLOCK:START -->
|
||
Call-site является **avoidable LLM control path** тогда и только тогда, когда выполнены **оба** условия:
|
||
- **(i)** это **C (control-path)** консультация — её LLM-вердикт потребляется потоком управления
|
||
(`check_*`-гейт ветвится на нём: PASS → дальше / FAIL → откат);
|
||
- **(ii)** вердикт **деривируем** (derivable) из tool-сигналов, которые оркестратор уже вычисляет сам —
|
||
exit-code `pytest` / smoke / `staging_check.py` / статус деплоя.
|
||
|
||
Если оба условия выполнены, суждение LLM не добавляет информации → консультацию можно снять без потери
|
||
смысла (заменить детерминированным раннером или гибридом с LLM-фолбэком только на не-деривируемую часть).
|
||
<!-- ORCH-118-AVOIDABLE-DEFINITION-BLOCK:END -->
|
||
|
||
**Поимённый целевой набор** (сверен с кодом, прибит тестами TC-13/TC-14):
|
||
|
||
- **avoidable LLM control paths = `{tester, deployer}`** — C **и** вердикт деривируем
|
||
(`result:` = exit-code `pytest`+smoke; `staging_status:` = маппинг exit-кода `staging_check.py`).
|
||
- **`reviewer`** — C, но **keep**: вердикт «приемлемость кода/решения» **НЕ деривируем** из exit-кода
|
||
(настоящее суждение). Это control-path-но-keep, **не** avoidable.
|
||
- **`analyst` / `architect` / `developer`** — **не** control path (**P**, artifact-producer):
|
||
детерминированный гейт судит артефакт независимо.
|
||
|
||
---
|
||
|
||
## 4. Критерии решения: keep vs replace
|
||
|
||
| Ситуация (по осям §2) | Решение | Класс |
|
||
|-----------------------|---------|-------|
|
||
| **P** — artifact-producer (детерминированный гейт судит артефакт) | **keep** LLM | `keep-LLM` |
|
||
| **C**, вердикт **НЕ деривируем** (настоящее суждение) | **keep** LLM (назвать суждение) | `keep-LLM` |
|
||
| **C**, вердикт **деривируем**, замена безопасна сейчас | **replace** | `replace-deterministic-now` |
|
||
| **C**, вердикт деривируем, но замена позже / с предпосылками | **replace later** | `replace-later/risky` |
|
||
| **C**, ядро деривируемо, но часть требует суждения | **hybrid** (детерм. ядро + LLM-фолбэк) | `needs-hybrid-fallback` |
|
||
|
||
> **keep-LLM требует обоснования:** любая `keep-LLM`-запись обязана **назвать конкретное суждение**;
|
||
> для C-keep — явно зафиксировать **не-деривируемость** вердикта (почему не сводится к exit-коду).
|
||
|
||
---
|
||
|
||
## 5. Требование к новым/изменённым control-path'ам (норматив)
|
||
|
||
- **Обоснование против политики.** Любой **новый** или изменённый control-path, который консультирует
|
||
LLM, обязан в своём ADR обосновать это против настоящей политики: показать, что он **P** (artifact
|
||
judged independently) **или** **C с не-деривируемым** вердиктом. C-консультация с деривируемым
|
||
вердиктом — это `avoidable`; её ввод без обоснования reviewer ловит как finding ≥P1.
|
||
- **Reviewer-ось (как ORCH-079) — требование, не реализация гейта.** Политика **рекомендует**
|
||
reviewer'у проверять соответствие новых control-path'ов настоящей политике; ORCH-118 **не** вводит
|
||
новый Quality Gate (`QG_CHECKS`/`check_*` не меняются) — это нормативное требование процесса.
|
||
- **Норматив сопровождения.** Меняешь место вызова LLM или потребителя вердикта в `src/qg/checks.py` →
|
||
обнови карту [`llm-call-sites.md`](llm-call-sites.md) и эту политику **в том же PR** (анти-дрейф
|
||
держат TC-13/TC-14).
|
||
- **Единственный транспорт.** Единственный разрешённый транспорт LLM-консультации в `src/**` — это
|
||
`launcher._spawn` (S0). Ввод второго транспорта (новый `_spawn`, импорт `anthropic`/`openai`/иного
|
||
LLM-SDK, прямой HTTP Anthropic/Claude, второй model-invoking subprocess) запрещён без явного ADR;
|
||
прибито тестами TC-01/TC-12.
|