Рефакторинг

README.md

@@ -54,7 +54,7 @@
 
 - **Target Architecture** описывает то, к чему проект идёт.
 - **MVP-now** описывает то, что реально доводится сейчас через тесты.
-- **MVP-now** не включает UI-интеграцию и не требует полного runtime orchestration.
+- **MVP-now** не включает UI-интеграцию и использует единый stage-based runtime.
 - **MVP-now** фокусируется на:
   - IntentRouterV2;
   - code-first retrieval;
@@ -72,9 +72,10 @@
 
 **MVP-now**
 
-- isolated `CODE_QA` test pipeline;
-- IntentRouterV2 as canonical router;
-- router-driven layered retrieval;
+- единый `agent runtime`;
+- `IntentRouterV2` как канонический router и retrieval planner;
+- stage-based execution внутри `agent.runtime`;
+- infrastructure `rag` только для indexing/retrieval/storage;
 - evidence-first answer synthesis;
 - diagnostics-first tuning;
 - no UI dependency;
@@ -870,9 +871,9 @@ flowchart TD
 **Target Architecture**
 
 - Router
-- Graphs / pipelines для `CODE`, `DOCS`, `CROSS_DOMAIN`, `GENERAL`
+- unified runtime
 - CODE RAG + DOCS RAG
-- evidence gate
+- evidence gates
 - synthesis layer
 - diagnostics
 - генерация технической документации из code / docs / system analysis
@@ -880,8 +881,8 @@ flowchart TD
 
 **MVP-now**
 
-- изолированный test-first пайплайн;
-- цепочка: `user query → IntentRouterV2 → retrieval plan → layered retrieval → evidence gate → LLM answer → diagnostics`;
+- единый test-first runtime;
+- цепочка: `user query → IntentRouterV2 → retrieval planning → runtime retrieval → context normalization → evidence gate 1 → answer policy → LLM answer → evidence gate 2 → finalization/diagnostics`;
 - основной домен: `CODE`;
 - основные сценарии:
   - `OPEN_FILE`
@@ -889,35 +890,42 @@ flowchart TD
   - `FIND_TESTS`
   - `FIND_ENTRYPOINTS`
   - `GENERAL_QA`
+  - `TRACE_FLOW`
+  - `ARCHITECTURE`
 - UI-интеграция не требуется для текущего этапа;
 - docs retrieval не обязателен для текущего milestone;
-- legacy `RouterService` не считается целевой архитектурой и в перспективе будет заменён.
+- legacy orchestration удалён из актуального execution path.
 
 ```mermaid
 flowchart TD
     U[User Query] --> R[IntentRouterV2]
-    R --> P[Retrieval Plan]
-    P --> G[Layered Retrieval]
-    G --> E[Evidence Gate]
-    E --> A[LLM Answer]
-    E --> D[Diagnostics]
-    A --> D
+    R --> P[Retrieval Planning]
+    P --> X[Runtime Retrieval]
+    X --> C[Context Normalization]
+    C --> E1[Evidence Gate 1]
+    E1 --> AP[Answer Policy]
+    AP --> A[LLM Answer]
+    AP --> D[Diagnostics]
+    A --> E2[Evidence Gate 2]
+    E2 --> F[Finalization]
+    F --> D
 ```
 
-Текущий milestone — test-first и code-first; этот пайплайн настраивается изолированно до интеграции в полный agent runtime.
+Текущий milestone — test-first и code-first; этот runtime уже является каноническим execution path для MVP.
 
-### 4.1.3. Канонический test-first пайплайн (CODE_QA)
+### 4.1.3. Канонический MVP runtime (CODE-first)
 
-Единая точка входа изолированного пайплайна — пакет `app.modules.rag.code_qa_pipeline`:
+Единая точка входа исполнения — пакет `app.modules.agent.runtime`:
 
-- **Роутер:** только `IntentRouterV2`; legacy `RouterService` не используется.
-- **Контракты:** `RouterResult` (IntentRouterResult), `RetrievalRequest`, `RetrievalResult`, `EvidenceBundle`, `AnswerSynthesisInput`, `DiagnosticsReport`.
-- **Цепочка:** запрос → IntentRouterV2 → RetrievalRequest → layered retrieval (через адаптер) → нормализованный RetrievalResult → EvidenceBundle → evidence gate → AnswerSynthesisInput → diagnostics.
-- **Evidence gate:** общая проверка достаточности evidence по сценарию (OPEN_FILE, EXPLAIN, FIND_TESTS, FIND_ENTRYPOINTS, GENERAL_QA); при недостатке — degraded/insufficient, без уверенного ответа.
-- **Диагностика:** Level 1 (summary) и Level 2 (detail), машинно-читаемые коды причин (`failure_reasons`: `target_not_resolved`, `path_scope_empty`, `layer_c0_empty`, `insufficient_evidence`, `tests_not_found`, `entrypoints_not_found` и др.).
-- **Запуск пайплайна в тестах:** `CodeQAPipelineRunner(router=..., retrieval_adapter=...)`; метод `run(user_query, rag_session_id)` возвращает `CodeQAPipelineResult` с полной диагностикой.
+- **Роутер:** `app.modules.agent.intent_router_v2`; он отвечает и за routing, и за retrieval planning.
+- **LLM-слой:** `app.modules.agent.llm`; здесь живут `AgentLlmService`, `PromptLoader` и системные prompt assets.
+- **Runtime:** `app.modules.agent.runtime`; внутри него stages разложены по подпакетам `retrieval`, `context`, `gates`, `answer_policy`, `generation`, `finalization`.
+- **Цепочка:** запрос → `IntentRouterV2` → retrieval planning → runtime retrieval adapter → нормализованный context/evidence → evidence gate 1 → answer policy → LLM generation → evidence gate 2 → finalization → diagnostics.
+- **Evidence gates:** pre/post проверки достаточности evidence и качества ответа по сценарию.
+- **Диагностика:** runtime возвращает machine-readable diagnostics и trace по стадиям.
+- **RAG:** `app.modules.rag` больше не содержит agent use-case слоев; он остается инфраструктурой indexing/retrieval/storage.
 
-Тесты: `tests/pipeline_setup/pipeline_intent_rag/test_canonical_code_qa_pipeline.py` (роутер → retrieval request, нормализованный результат, evidence gate, диагностика).
+Тесты: `pipeline_setup_v3` и связанные suite-ы проверяют канонический runtime и его stage-based execution.
 
 ## 4.2. Router
 
@@ -926,7 +934,7 @@ Router определяет:
 - intent;
 - sub-intent;
 - confidence;
-- подходящий graph;
+- подходящий execution path;
 - требования к retrieval plan.
 
 Целевые домены:
@@ -935,9 +943,22 @@ Router определяет:
 - `CROSS_DOMAIN`
 - `GENERAL`
 
-## 4.3. Graphs / pipelines
+## 4.3. Runtime Stages
 
-Graph — это специализированный сценарий обработки запроса.
+В текущем MVP execution path реализован не через graph engine, а через единый runtime с явными stage-компонентами.
+
+Текущие стадии:
+- `IntentRouterV2`
+- `retrieval planning`
+- `runtime retrieval`
+- `context normalization`
+- `evidence gate 1`
+- `answer policy`
+- `LLM generation`
+- `evidence gate 2`
+- `finalization + diagnostics`
+
+Если сценарии в будущем начнут расходиться по структуре, а не только по policy-логике шагов, следующим шагом будет рассмотрен переход на graph-based orchestration.
 
 Для MVP целесообразны как минимум:
 - `CodeOpenGraph`
@@ -1186,4 +1207,3 @@ DOCS и CROSS_DOMAIN остаются частью target architecture; в те
 - богатые fact-индексы по всем доменам;
 - полный reference graph документации;
 - глубокая автоматизация подготовки системной аналитики.
-