admin/orchestrator

Fork 0

Files

claude-bot 9710d5f80d

CI / test (push) Successful in 1m8s

Details

CI / test (pull_request) Successful in 1m10s

Details

docs(llm): LLM call-site map, control-path axis, roadmap & usage policy + anti-drift tests

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>

2026-06-16 00:13:07 +03:00

7.0 KiB

Raw Blame History

Блок 6. Качество и безопасность

Реестр гейтов и их распределение по стадиям — блок 2; механизм machine-verdict доков — PIPELINE_DOCS §3; машинный контракт стадий — HANDOFF_PROTOCOL.

Философия Quality Gates

Вердикты — машинные, никогда проза. Гейт читает вердикт ТОЛЬКО из YAML-frontmatter артефакта (ключи вида verdict:, result:, staging_status:, deploy_status:, security_status: — имена и регистр неизменны байт-в-байт). Агент не может «уговорить» гейт красивым отчётом: нет ключа — нет прохода. Парсинг frontmatter сведён к единому контракту src/frontmatter.py — одна точка чтения для всех гейтов.

Гейт ≠ маршрутизация. Маршруты задач (багфикс-трек, авто-лейблы, serial gate) — свойство планировщика; ни один из них не ослабляет ни одного гейта. Любая новая способность платформы проектируется так, чтобы реестр гейтов и карта стадий не трогались.

Анти-петля. Откаты на доработку ограничены (max 3 подряд); инструментальные сбои вспомогательных проверок по умолчанию fail-open с предупреждением (не запирают конвейер), критичные проверки — fail-closed.

Специальные гейты деплойного ребра

Security-гейт (check_security_gate) — детерминированная (без LLM) проверка секретов и зависимостей перед продом; вердикт — security_status: в отчёте задачи.
Coverage-гейт (check_coverage_gate) — покрытие тестами измеряется на финальном коде ветки; базовая линия по репозиторию растёт только вверх (ratchet при подтверждённом слиянии) — покрытие не может деградировать молча.

Оба — врезки в переход (блок 2), включаются по конфигу и скоупятся по репозиториям.

Канон секретов

Секреты живут только в .env-файлах на хосте и никогда не коммитятся; в git — только канон-примеры с пустыми плейсхолдерами.
Для нового хоста секреты выпускаются свежими (scripts/gen_secrets.py), боевые не копируются.
Анти-регресс машинный: структурные тесты сканируют исполняемый код на боевые хост-литералы, а документацию — на секретоподобные значения; находка рвёт CI.

Где уместен LLM: карта вызовов и нормативная политика

Платформа держит доказательную карту всех мест, где поток управления потребляет суждение LLM, и нормативную политику «LLM — только там, где нужно настоящее суждение». Карта разводит три факта: консультация ≠ транспорт/слот; control-path (вердикт LLM ветвит поток управления) ≠ artifact-producer (детерминированный гейт судит артефакт независимо); и деривируемость вердикта из tool-сигналов. Путь называется avoidable LLM control path, когда он одновременно control-path и его вердикт деривируем из exit-кодов (тогда консультацию можно заменить детерминированным раннером). Поимённо: avoidable = {tester, deployer}; настоящее суждение сохраняется у {analyst, architect, developer, reviewer}. Карта — снимок, прибитый структурными анти-дрейф тестами; реализация замен — отдельные follow-up'ы по роли.

Карта вызовов LLM: ../architecture/llm-call-sites.md
Нормативная политика: ../architecture/llm-usage-policy.md
Порядок замен: ../architecture/llm-determinization-roadmap.md

Self-hosting-страховки

Платформа дорабатывает сама себя тем же конвейером — прод-инстанс при этом обслуживает и другие проекты. Страховки:

Песочница обязательна: перед прод-выкладкой платформы изменение репетируется на staging-инстансе (отдельный порт/БД); guard не даёт staging-операциям коснуться прод-порта.
Прод-выкладка — только по явному человеческому статусу Confirm Deploy (обычный approve прод не выкатывает); деплой идёт детачнутым процессом с финализатором — честный исход фиксируется даже при рестарте.
main неприкосновенен: слияние только через PR-API, force-push запрещён всем.
Прод-контейнер никогда не роняется задачей: агенты проверяют изменения локально и на песочнице; рестарт прода — только штатным деплой-маршрутом.
Пост-деплой наблюдение: после выкладки платформа следит за своим здоровьем; деградация замораживает репозиторий и зовёт человека.

Операционные детали и топология прода — docs/operations/ (см. инженерный справочник); наблюдение за здоровьем — блок 7.

7.0 KiB Raw Blame History Unescape Escape