Документировать архитектуру агентного контура 1С

2026-05-23 23:04:07 +03:00 · 2026-05-23 23:04:07 +03:00 · 7f797e5346
parent f56bde3a45
commit 7f797e5346
1 changed files with 994 additions and 0 deletions
--- a/docs/ARCH/current_agent_architecture_2026-05-23.md
+++ b/docs/ARCH/current_agent_architecture_2026-05-23.md
@ -0,0 +1,994 @@
+# Архитектура текущего агентного контура NDC_1C
+
+Дата среза: 2026-05-23
+Статус документа: рабочая карта текущей реализации, собрана по коду, конфигам и orchestration-файлам репозитория.
+
+## 1. Коротко
+
+В проекте сейчас есть не один агент, а связка из двух больших контуров:
+
+1. Продуктовый 1С-ассистент.
+   Это backend/runtime, который принимает вопрос пользователя, нормализует смысл, выбирает маршрут, ходит в 1С/MCP, строит ответ и пишет debug/technical payload.
+
+2. Агентный контур разработки и контроля качества.
+   Это repo-native система прогонов, аудита, verdict/handoff и сохранения проверенных сценариев в autoruns. Его цель - снять с человека ручной разбор прогонов: запускать реальные сценарии, читать ответы как бизнес-пользователь, находить P0/P1/P2, формировать ремонтный handoff и не давать сохранять плохие сценарии как "успешные".
+
+Текущая важная мысль: **по умолчанию контур уже не является полностью авто-ремонтником**. Он автономно запускает, анализирует и формирует handoff, но код обычно чинит Lead Codex в основном контексте. Полностью автономный coder-режим есть, но он выключен по умолчанию и включается только явно через `repair_mode=auto-coder`.
+
+## 2. Сколько моделей участвует
+
+Ниже - фактическая карта ролей и моделей.
+
+| Слой | Роль | Модель/провайдер по текущим файлам | Температура | Лимит | Где задано |
+|---|---|---|---:|---:|---|
+| Product runtime LLM | LLM-нормализация / pre-decompose пользовательского вопроса | `local`, `unsloth/qwen3-30b-a3b-instruct-2507` | `0.8` | `900` | `llm_normalizer/data/shared_llm_connection.json` |
+| Domain case loop live runner | Запуск live case/scenario/pack против backend | по умолчанию берет shared config: `local`, `unsloth/qwen3-30b-a3b-instruct-2507` | `0.8` | `900` | `scripts/domain_case_loop.py` + `shared_llm_connection.json` |
+| Stage wrapper | Обертка stage-loop, если запускать без override | `local`, `qwen2.5-14b-instruct-1m` | `0.0` | `2048` | `scripts/stage_agent_loop.py` |
+| Codex analyst | Строгий read-only бизнес/технический аналитик | `gpt-5.4` | не через temperature, через reasoning effort | n/a | `.codex/agents/domain_analyst.toml`, `scripts/domain_case_loop.py` |
+| Codex coder | Implementation agent для минимального патча | `gpt-5.4` | reasoning effort | n/a | `.codex/agents/domain_coder.toml`, `scripts/domain_case_loop.py` |
+| Codex orchestrator | Координатор доменного цикла | `gpt-5.4` | reasoning effort | n/a | `.codex/agents/orchestrator.toml` |
+| Lead Codex | Основной интерактивный разработчик в текущем чате | модель текущей Codex-сессии, вне repo-конфига | n/a | n/a | не хранится в репозитории |
+
+Итого в текущей практической схеме участвуют минимум **4 модельные роли**:
+
+- локальная LLM для runtime-нормализации ассистента;
+- Codex analyst;
+- Codex coder;
+- Lead Codex.
+
+Если считать orchestrator как отдельную роль, получается **5 агентных ролей**, но orchestrator сейчас в основном описан как агентная маска/роль для внешнего Codex orchestration, а не как обязательный шаг каждого ручного цикла.
+
+## 3. Важное расхождение конфигов
+
+Есть два разных default-профиля локальной LLM:
+
+1. `scripts/domain_case_loop.py` читает `llm_normalizer/data/shared_llm_connection.json`.
+   Текущий shared config:
+
+   ```json
+   {
+     "llmProvider": "local",
+     "model": "unsloth/qwen3-30b-a3b-instruct-2507",
+     "baseUrl": "http://127.0.0.1:1234/v1",
+     "temperature": 0.8,
+     "maxOutputTokens": 900
+   }
+   ```
+
+2. `scripts/stage_agent_loop.py` имеет свои CLI defaults:
+
+   ```text
+   --llm-provider local
+   --llm-model qwen2.5-14b-instruct-1m
+   --llm-base-url http://127.0.0.1:1234/v1
+   --temperature 0.0
+   --max-output-tokens 2048
+   ```
+
+Практический вывод: если запускать `domain_case_loop.py` напрямую, он сейчас ориентируется на Qwen3 shared config. Если запускать через `stage_agent_loop.py` без override, stage wrapper передаст Qwen2.5 defaults. Это нужно помнить при сравнении прогонов.
+
+## 4. Основные порты и runtime-адреса
+
+| Компонент | Адрес/порт | Где задано |
+|---|---|---|
+| Backend 1С-ассистента | `http://127.0.0.1:8787` | `scripts/domain_case_loop.py`, `llm_normalizer/backend/src/config.ts` |
+| Local OpenAI-compatible LLM endpoint | `http://127.0.0.1:1234/v1` | `shared_llm_connection.json`, CLI defaults |
+| MCP proxy к 1С | `http://127.0.0.1:6003` | `llm_normalizer/backend/src/config.ts`, `ASSISTANT_MCP_PROXY_URL` |
+| MCP channel | `default` | `llm_normalizer/backend/src/config.ts`, `ASSISTANT_MCP_CHANNEL` |
+| MCP timeout | `6000 ms` | `ASSISTANT_MCP_TIMEOUT_MS` |
+| MCP live limit | `128` | `ASSISTANT_MCP_LIVE_LIMIT` |
+
+## 5. Product runtime: как отвечает 1С-ассистент
+
+Продуктовый runtime живет в `llm_normalizer/backend`.
+
+Грубый путь одного вопроса:
+
+1. Пользователь отправляет сообщение в backend.
+2. Backend собирает prompt bundle / normalizer prompt.
+3. LLM-нормализация или deterministic resolver определяют intent, filters, date scope, domain family.
+4. Orchestration решает lane:
+   - address lane;
+   - living chat;
+   - MCP discovery;
+   - exact capability route;
+   - bounded/limited answer.
+5. Address/MCP слой получает данные из 1С через proxy.
+6. Compose/answer policy строит human-facing answer.
+7. Параллельно пишется technical debug payload.
+8. Сессия сохраняется в `llm_normalizer/data/assistant_sessions`.
+
+Ключевые runtime-файлы:
+
+- `llm_normalizer/backend/src/services/assistantService.ts` - верхний слой ассистента.
+- `llm_normalizer/backend/src/services/addressQueryService.ts` - address query / exact route execution.
+- `llm_normalizer/backend/src/services/addressIntentResolver.ts` - распознавание address intent.
+- `llm_normalizer/backend/src/services/addressFilterExtractor.ts` - извлечение фильтров.
+- `llm_normalizer/backend/src/services/addressCapabilityPolicy.ts` - capability policy / feature gates.
+- `llm_normalizer/backend/src/services/addressNavigationState.ts` - состояние диалога, selected object, carryover.
+- `llm_normalizer/backend/src/services/assistantMcpDiscovery*` - discovery/bridge/handoff вокруг MCP.
+- `llm_normalizer/backend/src/services/address_runtime/*` - staged runtime для address lane.
+- `llm_normalizer/backend/src/config.ts` - флаги, порты, MCP settings.
+
+## 6. Prompt runtime продукта
+
+Главный backend prompt builder:
+
+- `llm_normalizer/backend/src/services/promptBuilder.ts`
+
+Он знает версии:
+
+- `normalizer_v1`
+- `normalizer_v1_1`
+- `normalizer_v1_1_1`
+- `normalizer_v1_1_2`
+- `normalizer_v1_1_2_1`
+- `normalizer_v2`
+- `normalizer_v2_0_1`
+- `normalizer_v2_0_2`
+
+Backend default:
+
+```text
+DEFAULT_PROMPT_VERSION = normalizer_v2_0_2
+```
+
+Текущий системный prompt-файл:
+
+- `llm_normalizer/backend/src/prompts/system/default.txt`
+
+Суть системной роли:
+
+```text
+Ты semantic-normalizer для бухгалтерского ассистента NDC.
+Твоя роль: только нормализация запроса пользователя в строгий JSON-контракт.
+Не давай бухгалтерский ответ по сути вопроса.
+Возвращай только JSON.
+```
+
+Фактическое дерево `llm_normalizer/backend/src/prompts` сейчас содержит только `default.txt` в подпапках:
+
+- `system/default.txt`
+- `developer/default.txt`
+- `domain/default.txt`
+- `fewshot/default.txt`
+
+При этом `promptBuilder.ts` декларирует version-specific файлы вроде `developer/normalizer_v2_0_2.txt`, `domain/normalizer_domain_v1_1.txt`, `fewshot/normalizer_v2_0_2.txt`. В текущем дереве этих файлов нет. Это отдельная зона аудита: либо runtime использует сохраненные presets из `llm_normalizer/data/presets`, либо часть built-in preset loader может быть недособрана для прямой загрузки `normalizer_v2_0_2`.
+
+Сохраненные preset-файлы:
+
+- `llm_normalizer/data/presets/preset-splJ9OGZ.json`
+- `llm_normalizer/data/presets/preset-rk8wKqPt.json`
+- `llm_normalizer/data/presets/preset-it0w_T10.json`
+
+Все найденные preset-файлы относятся к `normalizer_v1`, а не к `normalizer_v2_0_2`.
+
+## 7. Agentic semantic development loop: зачем он нужен
+
+Агентный контур нужен не для того, чтобы "модель сама по себе стала умнее", а чтобы построить повторяемую систему:
+
+1. Собрать реалистичный пакет вопросов.
+2. Прогнать его live против настоящего backend.
+3. Прочитать user-facing ответы как человек.
+4. Сравнить с business intent.
+5. Поставить P0/P1/P2.
+6. Объяснить root cause layer.
+7. Сформировать ремонтный handoff.
+8. После фикса прогнать тот же сценарий.
+9. Только после принятого live replay сохранить пакет в autoruns.
+
+Главный принцип из `AGENTS.md`: **семантический анализ важнее зеленых unit-тестов и route ids**. Route matched не считается успехом, если пользовательский ответ бизнесово неправильный.
+
+## 8. Главные файлы агентного контура
+
+| Файл | Роль |
+|---|---|
+| `scripts/domain_case_loop.py` | Основной движок case/scenario/pack/pack-loop. Запускает backend, пишет artifacts, строит business-first review, repair targets, analyst/coder prompts. |
+| `scripts/domain_truth_harness.py` | Live strict replay по JSON spec. Дает `truth_review`, `business_review`, `semantic_audit`, final status. |
+| `scripts/review_assistant_stage1_run.py` | Анализ уже сохраненных GUI/autorun прогонов. Строит business review, findings, repair targets. |
+| `scripts/stage_agent_loop.py` | Stage-level wrapper над `domain_case_loop.py`; умеет запускать stage loop, summarise, status, save autorun. |
+| `scripts/agent_semantic_pack_builder.py` | Сборщик целевых AGENT-паков из recipes/source catalog. |
+| `scripts/save_agent_semantic_run.py` | Сохраняет только уже validated replay в UI autoruns. Проверяет accepted artifacts. |
+| `.codex/skills/domain-case-loop/SKILL.md` | Правила работы доменного loop как навыка Codex. |
+| `.codex/agents/domain_analyst.toml` | Ролевая маска строгого аналитика. |
+| `.codex/agents/domain_coder.toml` | Ролевая маска кодера. |
+| `.codex/agents/orchestrator.toml` | Ролевая маска координатора. |
+| `docs/orchestration/active_domain_contract.json` | Текущий mutable domain contract. |
+| `docs/orchestration/stage_agent_loop_agentic_semantic_development_loop.json` | Stage manifest для dogfood gate агентного loop. |
+
+## 9. Роли агентного контура
+
+### 9.1 Lead Codex
+
+Это основной разработчик в текущем чате. Он:
+
+- читает репозиторий;
+- запускает harness;
+- делает patch через `apply_patch`;
+- запускает тесты;
+- коммитит;
+- обновляет Tasker;
+- принимает handoff от agent loop.
+
+Важно: Lead Codex не является repo-configured моделью. Его модель/лимиты задаются внешней средой Codex и в этом репозитории не фиксируются.
+
+### 9.2 Orchestrator
+
+Файл:
+
+- `.codex/agents/orchestrator.toml`
+
+Модель:
+
+```text
+gpt-5.4
+model_reasoning_effort = high
+sandbox_mode = workspace-write
+```
+
+Задача:
+
+- принять case/scenario;
+- создать artifact folder;
+- захватить baseline;
+- вызвать analyst;
+- передать coder минимальную задачу;
+- rerun;
+- запросить before/after verdict;
+- завершить статусом `accepted | partial | blocked | needs_exact_capability`.
+
+Жесткие ограничения:
+
+- не менять архитектуру;
+- не принимать heuristic output как confirmed answer;
+- не маскировать fallback;
+- принимать scenario tree, а не плоский список вопросов;
+- selected-object, pronoun follow-up, date carryover, field truth, answer layering являются обязательными acceptance target.
+
+### 9.3 Domain analyst
+
+Файл:
+
+- `.codex/agents/domain_analyst.toml`
+
+Модель:
+
+```text
+gpt-5.4
+model_reasoning_effort = high
+sandbox_mode = read-only
+```
+
+Задача:
+
+- читать artifacts, а не гадать по краткому пересказу;
+- судить бизнес-смысл ответа;
+- выделять P0/P1/P2;
+- отличать route gap, capability gap, business utility gap, field mapping gap, object memory gap, temporal honesty gap;
+- давать quality score 0-100;
+- запрещать acceptance ниже 80 или при unresolved P0.
+
+Ожидаемая структура prose verdict:
+
+1. Question meaning
+2. Primary user path and scenario tree
+3. Expected direct answer
+4. What the system actually computed
+5. Business mismatch
+6. Route / capability mismatch
+7. State continuity and selected-object memory
+8. Field truth and evidence quality
+9. P0 defects
+10. P1 defects
+11. P2 defects
+12. Minimal patch directions
+13. Acceptance matrix for rerun
+14. Acceptance criteria for rerun
+15. Quality score
+16. Loop decision
+
+### 9.4 Domain coder
+
+Файл:
+
+- `.codex/agents/domain_coder.toml`
+
+Модель:
+
+```text
+gpt-5.4
+model_reasoning_effort = high
+sandbox_mode = workspace-write
+```
+
+Задача:
+
+- читать verdict/handoff;
+- делать минимальный domain-only patch;
+- не менять широкую архитектуру;
+- не подменять exact data эвристикой;
+- сохранять successful baseline flows.
+
+Разрешенные зоны:
+
+- intents;
+- domain-specific routing;
+- recipes;
+- capability mapping;
+- exact/confirmed route handling;
+- domain validators;
+- evidence/source-ref modeling;
+- role modeling;
+- follow-up resolution;
+- business-readable presentation.
+
+Запрещено:
+
+- broad architecture changes;
+- fake data;
+- silent heuristic masking;
+- large unrelated refactors.
+
+### 9.5 Deterministic reviewer
+
+Это не LLM-модель, а код.
+
+Главные места:
+
+- `scripts/domain_case_loop.py::build_business_first_review`
+- `scripts/domain_truth_harness.py::build_business_review_summary`
+- `scripts/review_assistant_stage1_run.py::augment_gui_business_review`
+
+Что он умеет проверять:
+
+- direct answer first;
+- technical garbage;
+- top-level scaffolding;
+- overly verbose direct answer;
+- counterparty net-flow vs company profit misroute;
+- bank role misclassification;
+- domain leak for nomenclature margin questions;
+- missing accounting contract;
+- missing next action for limited margin answer.
+
+Последние добавленные issue-коды:
+
+- `domain_leak_accounting_route` - P0;
+- `accounting_contract_missing` - P1;
+- `business_next_step_missing` - P2.
+
+## 10. Режимы запуска agent loop
+
+### 10.1 Case mode
+
+Команда:
+
+```powershell
+python scripts/domain_case_loop.py run-case --domain <domain> --question "<question>"
+```
+
+Используется для одного конкретного вопроса.
+
+Артефакты:
+
+- `baseline_output.md`
+- `baseline_debug.json`
+- `baseline_turn.json`
+- `baseline_session.json`
+- `baseline_job.json`
+
+### 10.2 Scenario mode
+
+Команда:
+
+```powershell
+python scripts/domain_case_loop.py run-scenario --manifest <manifest.json>
+```
+
+Используется для одной цепочки вопросов в одной assistant session.
+
+Артефакты:
+
+- `scenario_manifest.json`
+- `scenario_state.json`
+- `scenario_summary.md`
+- `steps/<step_id>/turn.json`
+- `steps/<step_id>/debug.json`
+- `steps/<step_id>/output.md`
+- `steps/<step_id>/step_state.json`
+
+### 10.3 Pack mode
+
+Команда:
+
+```powershell
+python scripts/domain_case_loop.py run-pack --manifest <pack.json>
+```
+
+Используется для нескольких сценариев внутри одного доменного пакета.
+
+Артефакты:
+
+- `pack_state.json`
+- `pack_summary.md`
+- `repair_targets.json`
+- `scenario_acceptance_matrix.md`
+- `scenarios/<scenario_id>/...`
+
+### 10.4 Autonomous pack-loop mode
+
+Команда:
+
+```powershell
+python scripts/domain_case_loop.py run-pack-loop --manifest <pack.json>
+```
+
+Что делает:
+
+1. Запускает `run-pack`.
+2. Собирает evidence bundle.
+3. Строит deterministic repair targets.
+4. Вызывает Codex analyst.
+5. Пишет `business_audit.md`.
+6. Если не accepted:
+   - при `lead-handoff` пишет `lead_coder_handoff.md` и останавливается;
+   - при `auto-coder` вызывает Codex coder.
+7. После coder-патча должен быть rerun.
+
+Текущий default repair mode:
+
+```text
+lead-handoff
+```
+
+Это принципиально: агент не должен сам бесконтрольно править runtime, пока не доказано, что auto-coder достаточно надежен.
+
+### 10.5 Truth harness live replay
+
+Команда:
+
+```powershell
+python scripts/domain_truth_harness.py run-live --spec <spec.json> --output-dir artifacts/domain_runs/<run_id>
+```
+
+Артефакты:
+
+- `final_status.md`
+- `truth_review.md/json`
+- `business_review.md/json`
+- `semantic_audit.md/json`
+- `pack_state.json`
+- `steps/<step_id>/turn.json`
+- `steps/<step_id>/output.md`
+
+Это сейчас самый удобный механизм для целевых AGENT-прогонов.
+
+### 10.6 Save validated AGENT run to autoruns
+
+Команда:
+
+```powershell
+python scripts/save_agent_semantic_run.py --spec <spec.json> --validated-run-dir <accepted_artifact_dir>
+```
+
+Ограничение:
+
+- нельзя сохранять pack в autoruns до live replay;
+- save-script проверяет `truth_review.json`, `business_review.json`, accepted/pass status;
+- unvalidated save возможен только через явный `--allow-unvalidated`, но по правилам проекта это invalid intermediate artifact для боевых паков.
+
+## 11. Stage-level AGENT loop
+
+Stage manifest:
+
+- `docs/orchestration/stage_agent_loop_agentic_semantic_development_loop.json`
+
+Ключевые параметры:
+
+```json
+{
+  "stage_id": "agentic_semantic_development_loop",
+  "module_name": "Agentic Semantic Development Loop",
+  "target_score": 88,
+  "max_iterations": 6,
+  "repair_mode": "lead-handoff",
+  "save_autorun_on_accept": true,
+  "manual_confirmation_required_after_accept": true
+}
+```
+
+Acceptance invariants:
+
+- status command exposes next action / repair state / validation state;
+- run-pack-loop defaults to Lead Codex handoff;
+- continue command never runs real coder pass without `--execute-repair`;
+- `business_audit.md` and `lead_coder_handoff.md` are produced before code repair when semantic replay is not accepted;
+- patched repair cannot close stage without rerun validation;
+- business answers remain direct/context-aware/free of debug IDs;
+- manual GUI confirmation remains required after accepted semantic replay.
+
+Stage wrapper:
+
+- `scripts/stage_agent_loop.py`
+
+Основные команды:
+
+```powershell
+python scripts/stage_agent_loop.py plan --manifest docs/orchestration/stage_agent_loop_agentic_semantic_development_loop.json
+python scripts/stage_agent_loop.py run --manifest docs/orchestration/stage_agent_loop_agentic_semantic_development_loop.json
+python scripts/stage_agent_loop.py status --manifest docs/orchestration/stage_agent_loop_agentic_semantic_development_loop.json
+python scripts/stage_agent_loop.py summarize --manifest docs/orchestration/stage_agent_loop_agentic_semantic_development_loop.json
+```
+
+## 12. Current active domain contract
+
+Файл:
+
+- `docs/orchestration/active_domain_contract.json`
+
+Текущий domain:
+
+```text
+inventory_stock_supplier_provenance
+```
+
+Смысл:
+
+- складские остатки на дату;
+- выбранная номенклатура;
+- поставщик;
+- закупочные документы;
+- возраст закупки;
+- дальнейшая продажа;
+- selected-object continuity;
+- pronoun follow-up;
+- temporal carryover.
+
+Правило из контракта:
+
+- стабильные слои: `AGENTS.md`, `.codex/skills/domain-case-loop`, `.codex/agents/*.toml`;
+- mutable слой: `docs/orchestration/active_domain_contract.json`;
+- при смене домена надо менять active contract, а не переписывать agent canon.
+
+## 13. Как агент оценивает качество
+
+### 13.1 Основной порядок анализа
+
+Проектное правило:
+
+1. Читать цепочку пользовательских вопросов как человеческий разговор.
+2. Читать ответы ассистента как их видит пользователь.
+3. Оценить semantic correctness, context awareness, directness, usefulness.
+4. Только потом смотреть debug payload, route ids, capability ids, filters.
+5. Только после этого смотреть unit tests / narrow regressions.
+
+Это зашито в `AGENTS.md` и поддерживается `business_first_review`.
+
+### 13.2 Виды итогового статуса
+
+Используются статусы:
+
+- `accepted` - можно считать сценарий принятым;
+- `partial` - есть рабочая часть, но качество/coverage недостаточно;
+- `blocked` - инфраструктурный или реальный hard blocker;
+- `needs_exact_capability` - запрос валиден для проекта, но не хватает capability/route/контракта.
+
+### 13.3 Severity
+
+Практическая шкала:
+
+- P0 - смысловая или архитектурная поломка, нельзя принимать;
+- P1 - важная проблема качества/контракта, обычно блокирует "хорошую базу";
+- P2 - полезная доработка, не всегда blocker;
+- warning/info - поддерживающие сигналы.
+
+Примеры P0:
+
+- wrong intent;
+- wrong capability;
+- wrong recipe;
+- wrong date/period;
+- missing required filter;
+- focus object missing;
+- business direct answer missing;
+- technical garbage in answer;
+- counterparty net-flow misrouted to company profit;
+- domain leak accounting route.
+
+Примеры P1:
+
+- answer layering noise;
+- business answer too verbose;
+- accounting contract missing.
+
+Пример P2:
+
+- limited margin answer without next action.
+
+## 14. Что считается хорошим ответом
+
+Общие правила:
+
+- direct answer first;
+- business meaning first, proof second, service notes last;
+- no route/debug/internal ids in user-facing answer;
+- no row counts before business answer;
+- no `status`, `what was considered`, `exact contour`, `coverage`, `truth gate` above the answer;
+- selected-object follow-up must be action-first, not trace-first;
+- if exact fact unavailable, answer must say what is confirmed, what is inferred, what remains unknown;
+- limited answer must still give useful next action when domain expects it.
+
+Для маржинальности номенклатуры агент теперь ожидает:
+
+- период;
+- выручку;
+- себестоимость;
+- валовую прибыль;
+- маржу;
+- если данных не хватает - честный отказ плюс следующий шаг.
+
+Запрещенная доменная протечка для маржинальности:
+
+- ОС;
+- амортизация;
+- банковские списания;
+- payment_document;
+- unresolved settlement;
+- зависшие оплаты;
+- закрытие расчетов вместо реализации/себестоимости.
+
+## 15. Artifact topology
+
+Главные каталоги:
+
+```text
+artifacts/domain_runs/
+llm_normalizer/data/assistant_sessions/
+llm_normalizer/reports/
+llm_normalizer/data/autorun_generators/
+llm_normalizer/data/eval_cases/
+docs/orchestration/
+```
+
+Что где лежит:
+
+- live run artifacts: `artifacts/domain_runs/<run_id>/`;
+- session JSON: `llm_normalizer/data/assistant_sessions/<session_id>.json`;
+- saved autorun sessions: `llm_normalizer/data/autorun_generators/saved_sessions/`;
+- generated eval cases: `llm_normalizer/data/eval_cases/`;
+- autorun history: `llm_normalizer/data/autorun_generators/history.json`;
+- specs/manifests: `docs/orchestration/*.json`;
+- stage loop artifacts: `artifacts/domain_runs/stage_agent_loops/`.
+
+## 16. Как pack попадает в UI autoruns
+
+Правильный порядок:
+
+1. Создать или обновить spec.
+2. Выполнить live replay:
+
+   ```powershell
+   python scripts/domain_truth_harness.py run-live --spec docs/orchestration/<spec>.json --output-dir artifacts/domain_runs/<run_id>
+   ```
+
+3. Проверить:
+   - `final_status.md`;
+   - `semantic_audit.md/json`;
+   - `truth_review.md/json`;
+   - step-level `output.md` / `turn.json`.
+4. Если статус accepted и semantic gate pass, сохранить:
+
+   ```powershell
+   python scripts/save_agent_semantic_run.py --spec docs/orchestration/<spec>.json --validated-run-dir artifacts/domain_runs/<run_id>
+   ```
+
+5. В UI pack появится как `AGENT | ...`.
+
+Если pack сохранен раньше live replay, по правилам проекта это мусорный intermediate artifact, его надо удалить и пересоздать.
+
+## 17. Текущие сохраненные AGENT-паки
+
+Недавние важные specs:
+
+- `docs/orchestration/agent_autonomy_business_quality_20260523.json`
+- `docs/orchestration/agent_autonomy_selected_object_mix_20260523.json`
+- `docs/orchestration/agent_inventory_margin_ranking_20260523.json`
+- `docs/orchestration/agent_profit_direct_answer_20260523.json`
+- `docs/orchestration/agent_cashflow_profit_directness_20260523.json`
+- `docs/orchestration/agent_cashflow_no_tops_20260523.json`
+- `docs/orchestration/inventory_margin_ranking_agent_loop_20260522.json`
+
+Пример принятого pack:
+
+- `agent_autonomy_selected_object_mix_20260523`
+- live replay: 15/15;
+- status: `accepted`;
+- сохранен в autoruns как `AGENT | selected-object + multi-org context mix`.
+
+## 18. Как анализируется GUI/autorun прогон
+
+Файл:
+
+- `scripts/review_assistant_stage1_run.py`
+
+Назначение:
+
+- взять сохраненные assistant sessions;
+- собрать пары user/assistant;
+- извлечь user-facing ответ;
+- дополнить business review;
+- найти issue codes;
+- сгруппировать repair targets;
+- записать markdown/json отчет.
+
+Особые детекторы:
+
+- technical leaks;
+- bank role misclassification;
+- counterparty value-flow -> company profit slip;
+- margin domain leak;
+- direct answer missing;
+- top-line scaffolding;
+- verbosity.
+
+## 19. Где находятся ролевые маски и ограничения
+
+### Agent masks
+
+- `.codex/agents/orchestrator.toml`
+- `.codex/agents/domain_analyst.toml`
+- `.codex/agents/domain_coder.toml`
+
+### Skill rules
+
+- `.codex/skills/domain-case-loop/SKILL.md`
+- `.codex/skills/domain-case-loop/references/business_first_analyst_rubric.md`
+- `.codex/skills/domain-case-loop/references/scenario_tree_acceptance_canon.md`
+- `.codex/skills/domain-case-loop/references/verdict_template.md`
+- `.codex/skills/domain-case-loop/references/repo_runtime_map.md`
+
+### Project rules
+
+- `AGENTS.md`
+
+Ключевые ограничения из `AGENTS.md`:
+
+- UTF-8 without BOM;
+- после code changes обновлять graphify;
+- acceptance через semantic answer, не только tests;
+- valid multi-org clarification не считать bug;
+- если multi-company contour требует уточнения, replay должен продолжить с выбором компании;
+- не сохранять AGENT pack в autoruns до accepted live replay;
+- не принимать domain, если root работает, а selected-object/drilldown edges ломаются;
+- no silent heuristic masking.
+
+### Runtime feature flags
+
+- `llm_normalizer/backend/src/config.ts`
+
+Примеры включенных флагов:
+
+- `FEATURE_ASSISTANT_ADDRESS_QUERY_V1 = true`
+- `FEATURE_ASSISTANT_ADDRESS_QUERY_LLM_PREDECOMPOSE_V1 = true`
+- `FEATURE_ASSISTANT_ADDRESS_QUERY_LIVE_V1 = true`
+- `FEATURE_ASSISTANT_ADDRESS_NAVIGATION_STATE_V1 = true`
+- `FEATURE_ASSISTANT_CAPABILITY_ROUTE_GUARD_V1 = true`
+- `FEATURE_ASSISTANT_ROUTE_EXPECTATION_AUDIT_V1 = true`
+- `FEATURE_ASSISTANT_LIVING_CHAT_ROUTER_V1 = true`
+
+Примеры выключенных/опасных:
+
+- `FEATURE_ASSISTANT_MCP_RUNTIME_V1 = false`
+- `FEATURE_ASSISTANT_ROUTE_EXPECTATION_HARD_GUARD_V1 = false`
+- `FEATURE_ASSISTANT_STAGE2_EVAL_V1 = false`
+
+## 20. Что автоматизировано, а что нет
+
+Автоматизировано:
+
+- capture baseline/rerun;
+- live scenario replay;
+- semantic audit artifact generation;
+- deterministic issue detection;
+- repair target grouping;
+- Codex analyst verdict;
+- Lead Codex handoff;
+- validated autorun save;
+- stage status/summary.
+
+Частично автоматизировано:
+
+- code repair через Codex coder.
+
+Почему частично:
+
+- `auto-coder` существует, но выключен по умолчанию;
+- default `repair_mode = lead-handoff`;
+- агент пишет handoff, а Lead Codex применяет патч в основном контексте;
+- это сделано осознанно, чтобы не получить слабый авто-патч с architecture drift.
+
+Не автоматизировано полностью:
+
+- финальное продуктово-бухгалтерское решение спорных бизнес-рамок;
+- опасные architecture forks;
+- выбор между разными учетными моделями, если данных/политики не хватает;
+- гарантированная 100% оценка всех доменов без целевых packs.
+
+## 21. Текущий уровень зрелости агента
+
+Что уже хорошо:
+
+- умеет запускать real backend replay;
+- умеет сохранять step-level artifacts;
+- умеет semantic gate;
+- умеет selected-object continuity checks;
+- умеет multi-org clarification continuation;
+- умеет сохранять validated packs в UI autoruns;
+- умеет ловить техмусор и несколько бизнесовых P0;
+- умеет формировать repair handoff.
+
+Что еще надо качать:
+
+- сильный analyst verdict уровня ручного аудита на каждый новый домен;
+- больше domain-specific semantic detectors;
+- auto-coder пока не default;
+- prompt/preset registry требует отдельной ревизии;
+- stage wrapper defaults и shared LLM defaults надо унифицировать или явно документировать в CLI;
+- больше целевых packs по бухгалтерским доменам: маржинальность, себестоимость, прибыль, НДС, долги, склад, взаиморасчеты.
+
+## 22. Текущие риски
+
+### 22.1 Разные defaults моделей
+
+`domain_case_loop.py` и `stage_agent_loop.py` могут запускать разные local LLM defaults.
+
+Риск:
+
+- один и тот же pack может вести себя по-разному при прямом и stage-запуске.
+
+Что сделать:
+
+- унифицировать stage wrapper с shared LLM config или явно писать effective model в каждый artifact.
+
+### 22.2 Prompt preset registry не полностью прозрачен
+
+`promptBuilder.ts` декларирует version-specific files, но в prompt-директории сейчас видны только default files.
+
+Риск:
+
+- прямой built-in load для `normalizer_v2_0_2` может зависеть от отсутствующих файлов или от сохраненных presets неочевидным образом.
+
+Что сделать:
+
+- отдельный audit prompt registry;
+- документировать active prompt source in runtime;
+- добавить health check на prompt file presence.
+
+### 22.3 Semantic gate еще не равен бухгалтеру
+
+Deterministic review уже ловит часть P0/P1, но не все.
+
+Риск:
+
+- новый домен может пройти route-level checks, но быть бизнесово слабым.
+
+Что сделать:
+
+- добавлять domain-specific detectors по мере появления ручных аудитов;
+- сохранять плохие и хорошие примеры как unit tests review layer.
+
+### 22.4 Auto-coder выключен
+
+Это скорее плюс по безопасности, но минус по автономности.
+
+Риск:
+
+- агент не закрывает цикл полностью сам.
+
+Что сделать:
+
+- сначала довести analyst/handoff до стабильно высокого качества;
+- затем включать auto-coder только на низкорисковых scoped domains.
+
+## 23. Быстрая карта "кто за что отвечает"
+
+| Вопрос | Ответ |
+|---|---|
+| Кто отвечает пользователю в UI? | Product runtime в `llm_normalizer/backend`. |
+| Кто нормализует вопрос? | Local LLM + deterministic resolvers. |
+| Какая локальная модель сейчас в shared config? | `unsloth/qwen3-30b-a3b-instruct-2507`. |
+| Кто запускает live replay? | `domain_truth_harness.py` или `domain_case_loop.py`. |
+| Кто пишет semantic audit? | `domain_truth_harness.py` + `domain_case_loop.py::business_first_review`. |
+| Кто анализирует GUI-прогоны? | `review_assistant_stage1_run.py`. |
+| Кто делает строгий LLM-verdict? | `domain_analyst` на `gpt-5.4`. |
+| Кто должен чинить код в auto режиме? | `domain_coder` на `gpt-5.4`, но auto-coder не default. |
+| Кто чинит код сейчас обычно? | Lead Codex по handoff. |
+| Где текущий активный домен? | `docs/orchestration/active_domain_contract.json`. |
+| Где сохраненные AGENT autoruns? | `llm_normalizer/data/autorun_generators/saved_sessions/`. |
+| Где история autorun генерации? | `llm_normalizer/data/autorun_generators/history.json`. |
+| Где stage manifest агентного loop? | `docs/orchestration/stage_agent_loop_agentic_semantic_development_loop.json`. |
+
+## 24. Минимальная команда для текущего целевого AGENT-прогона
+
+Пример live replay:
+
+```powershell
+python scripts/domain_truth_harness.py run-live `
+  --spec docs/orchestration/agent_autonomy_selected_object_mix_20260523.json `
+  --output-dir artifacts/domain_runs/agent_autonomy_selected_object_mix_live_manual
+```
+
+Проверить:
+
+```powershell
+Get-Content artifacts/domain_runs/agent_autonomy_selected_object_mix_live_manual/final_status.md
+Get-Content artifacts/domain_runs/agent_autonomy_selected_object_mix_live_manual/semantic_audit.md
+Get-Content artifacts/domain_runs/agent_autonomy_selected_object_mix_live_manual/truth_review.md
+```
+
+Сохранить в autoruns только если accepted:
+
+```powershell
+python scripts/save_agent_semantic_run.py `
+  --spec docs/orchestration/agent_autonomy_selected_object_mix_20260523.json `
+  --validated-run-dir artifacts/domain_runs/agent_autonomy_selected_object_mix_live_manual
+```
+
+## 25. Как читать результаты агента
+
+Правильный порядок:
+
+1. `final_status.md`
+2. `semantic_audit.md`
+3. `truth_review.md`
+4. `pack_state.json`
+5. `steps/<step_id>/output.md`
+6. `steps/<step_id>/turn.json`
+
+Не надо начинать с route ids. Сначала читается human-facing answer.
+
+## 26. Что значит "качать агента дальше"
+
+В текущей архитектуре "качать агента" означает:
+
+1. Улучшать business-first review.
+2. Добавлять domain-specific semantic detectors.
+3. Строить целевые AGENT packs по свежим больным темам.
+4. Требовать live replay до autorun save.
+5. Делать accepted gate не по route/pass, а по human answer quality.
+6. Расширять analyst verdict/handoff так, чтобы Lead Codex получал почти готовый repair plan.
+7. Постепенно приближать auto-coder к безопасному default, но не раньше, чем analyst gate станет надежным.
+
+Ближайший правильный домен для прокачки:
+
+- маржинальность / прибыльность номенклатуры;
+- выручка без НДС;
+- себестоимость реализации;
+- валовая прибыль;
+- маржа;
+- честный отказ, если данных мало;
+- next action, если рейтинг нельзя построить.
+
+## 27. Источники для этого документа
+
+Ключевые источники:
+
+- `AGENTS.md`
+- `graphify-out/GRAPH_REPORT.md`
+- `.codex/skills/domain-case-loop/SKILL.md`
+- `.codex/skills/domain-case-loop/references/repo_runtime_map.md`
+- `.codex/skills/domain-case-loop/references/business_first_analyst_rubric.md`
+- `.codex/agents/orchestrator.toml`
+- `.codex/agents/domain_analyst.toml`
+- `.codex/agents/domain_coder.toml`
+- `scripts/domain_case_loop.py`
+- `scripts/domain_truth_harness.py`
+- `scripts/review_assistant_stage1_run.py`
+- `scripts/stage_agent_loop.py`
+- `scripts/save_agent_semantic_run.py`
+- `scripts/agent_semantic_pack_builder.py`
+- `llm_normalizer/data/shared_llm_connection.json`
+- `llm_normalizer/backend/src/config.ts`
+- `llm_normalizer/backend/src/services/promptBuilder.ts`
+- `docs/orchestration/active_domain_contract.json`
+- `docs/orchestration/stage_agent_loop_agentic_semantic_development_loop.json`