Роутер работает нормально в process v2

_process/03. Intents.md

@@ -0,0 +1,59 @@
+# Intents
+
+## Domains
+
+- `DOCS`
+- `GENERAL`
+- `CODE` - временно отключен
+
+## GENERAL
+
+### Intent `GENERAL_QA`
+
+Общий интент для вопросов без точного маршрута.
+В дальнейшем может использоваться как fallback.
+
+Subintents:
+- `SUMMARY` - ответы на общие вопросы по SUMMARY
+
+
+
+## DOCS
+
+### Intent `ARCHITECTURE`
+
+Обработка вопросов по архитектуре.
+Subintents пока отсутствуют.
+Интент запланирован, без реализации.
+
+### Intent `DOC_EXPLAIN`
+
+Объяснение по документации.
+
+Subintents:
+- `SUMMARY` - краткое объяснение темы по SUMMARY-блокам документации
+- `FIND_FILES` - поиск файлов с релевантной информацией
+- `EXPLAIN_API` - объяснение работы метода
+- `COMPONENT_INTEGRATIONS` - перечень интеграций компонента, API, UI, сущности, внешних систем
+- `ENTITY_INTEGRATIONS` - перечень интеграций сущности
+
+В текущем узком MVP реально реализованы только:
+
+- `SUMMARY`
+- `FIND_FILES`
+
+Для запросов по интеграциям целевым retrieval-слоем является `D6_INTEGRATION_INDEX`.
+
+### Intent `OPENAPI_GENERATION`
+
+Генерация OpenAPI-спеки.
+
+Subintents:
+- `FULL_SPEC` - создание полной спецификации
+
+### Intent `DOC_GENERATION`
+
+Редактирование документации.
+
+Subintents:
+- `FROM_FEATURE` - создание документации из системной аналитики на фичу

_process/03. RAG.md

@@ -0,0 +1,356 @@
+# RAG
+
+## Состояние as is
+
+RAG сейчас используется как общее ядро индексации и retrieval по коду и документации.
+Основной storage - `rag_session` и многослойный индекс в БД.
+
+## Основные части
+
+- `RagService` - фасад индексации и retrieval
+- `DocsIndexingPipeline` - индексация документации
+- `CodeIndexingPipeline` - индексация кода
+- `RagRepository` - persistence и retrieval
+- `IntentRouterV2` - планирование retrieval: слои, фильтры, ограничения
+- `RuntimeRetrievalAdapter` - выполнение retrieval в runtime
+
+## Индексация
+
+Индексация идет по двум направлениям:
+
+- `DOCS`
+- `CODE`
+
+На вход подается snapshot или changes.
+Для каждого файла выбирается подходящий pipeline.
+На выходе формируются документы по слоям и сохраняются в RAG-хранилище.
+
+## Структура БД
+
+Все слои сохраняются в общую таблицу `rag_chunks`.
+
+### Общие поля по слоям
+
+| Поле БД | Назначение |
+|---|---|
+| `rag_session_id` | идентификатор сессии индексации |
+| `path` | путь исходного файла |
+| `content` | основной текст записи для retrieval |
+| `layer` | идентификатор слоя |
+| `title` | короткий заголовок записи |
+| `lang` | язык исходного содержимого, в основном для code-слоев |
+| `repo_id` | идентификатор репозитория или проекта |
+| `commit_sha` | версия кода или документов на момент индексации |
+| `span_start`, `span_end` | диапазон строк в исходном файле, если он есть |
+| `embedding` | векторное представление записи |
+| `metadata_json` | структурированные атрибуты конкретного слоя |
+
+### Поля со смыслом слоя
+
+Смысл конкретного слоя хранится в `metadata_json`.
+Именно эти атрибуты определяют, какой объект был извлечен и как его интерпретировать в retrieval.
+Домены и поддомены должны храниться в `metadata_json` явно.
+
+## Слои DOCS
+
+### `D0_DOC_CHUNKS`
+
+Задача:
+Хранит текстовые фрагменты документации для retrieval по содержимому разделов.
+
+Формирование:
+Документ сначала разбирается на frontmatter и body, затем body режется на секции через markdown chunker.
+Для каждой секции создается отдельная запись слоя.
+Нарезка идет по разделам документа.
+Только в fallback-сценарии, когда markdown-структура не найдена, используется нарезка по фиксированным текстовым чанкам.
+
+Фиксация в БД:
+| Атрибут в `metadata_json` | Описание | Источник |
+|---|---|---|
+| `document_id` | идентификатор документа-источника | `frontmatter.id`, иначе путь файла |
+| `type` | тип документа из frontmatter | `frontmatter.type` |
+| `module` | модуль документа | `frontmatter.module` |
+| `domain` | домен документа | `frontmatter.domain` |
+| `subdomain` | поддомен документа | `frontmatter.subdomain` |
+| `tags` | теги документа | `frontmatter.tags` |
+| `section_path` | полный путь секции в иерархии заголовков | результат `MarkdownDocChunker` |
+| `section_title` | заголовок текущей секции | результат `MarkdownDocChunker` |
+| `order` | порядок секции внутри документа | результат `MarkdownDocChunker` |
+| `doc_kind` | классификация документа, например `readme`, `spec`, `runbook` | `DocsClassifier.classify(path)` |
+| `source_path` | исходный путь документа | путь файла |
+| `artifact_type` | тип артефакта, здесь `DOCS` | константа builder |
+
+Связанные классы:
+`DocsIndexingPipeline`, `DocsContentParser`, `MarkdownDocChunker`, `DocsDocumentBuilder`
+
+### `D1_DOCUMENT_CATALOG`
+
+Задача:
+Хранит карточку документа как точку входа в документ и его краткое описание.
+
+Формирование:
+Источник данных - frontmatter, fallback title, summary и doc kind, вычисленный классификатором документации.
+Данные извлекаются структурированно по атрибутам.
+В `content` попадает summary документа, а не склейка всех частей документа в сплошной текст.
+
+Фиксация в БД:
+| Атрибут в `metadata_json` | Описание | Источник |
+|---|---|---|
+| `document_id` | идентификатор документа | `frontmatter.id`, иначе путь файла |
+| `type` | тип документа из frontmatter | `frontmatter.type` |
+| `name` | системное имя документа | `frontmatter.name` |
+| `title` | человекочитаемый заголовок документа | `frontmatter.title`, иначе fallback title |
+| `module` | модуль документа | `frontmatter.module` |
+| `domain` | домен документа | `frontmatter.domain` |
+| `subdomain` | поддомен документа | `frontmatter.subdomain` |
+| `layer` | логический слой, указанный в frontmatter документа | `frontmatter.layer` |
+| `status` | статус документа | `frontmatter.status` |
+| `updated_at` | дата или отметка последнего обновления | `frontmatter.updated_at` |
+| `tags` | теги документа | `frontmatter.tags` |
+| `entities` | сущности, связанные с документом | `frontmatter.entities` |
+| `parent` | родительский документ | `frontmatter.parent` |
+| `children` | дочерние документы | `frontmatter.children` |
+| `links` | ссылки на связанные материалы | `frontmatter.links` |
+| `source_path` | исходный путь документа | путь файла |
+| `summary_text` | краткое содержание документа | секция `# Summary` |
+| `doc_kind` | классификация документа, например `readme`, `spec`, `runbook` | `DocsClassifier.classify(path)` |
+
+Связанные классы:
+`DocsIndexingPipeline`, `DocsFrontmatterParser`, `DocsClassifier`, `DocsContentParser`, `DocsDocumentBuilder`
+
+### `D2_FACT_INDEX`
+
+Задача:
+Хранит атомарные факты в форме `subject-predicate-object` для точного retrieval по утверждениям.
+
+Формирование:
+Факты извлекаются из frontmatter и секций документа, после чего каждая найденная тройка превращается в отдельную запись.
+
+Фиксация в БД:
+| Атрибут в `metadata_json` | Описание | Источник |
+|---|---|---|
+| `fact_id` | идентификатор факта | вычисляется builder из содержимого факта и пути |
+| `subject_id` | субъект факта | `DocsFactExtractor` |
+| `predicate` | предикат или тип связи | `DocsFactExtractor` |
+| `object` | значение или объект факта | `DocsFactExtractor` |
+| `object_ref` | ссылка на объект, если она выделена отдельно | `DocsFactExtractor` |
+| `anchor` | место в документе, откуда взят факт | `DocsFactExtractor` |
+| `tags` | теги факта | `DocsFactExtractor` |
+| `source_path` | исходный путь документа | путь файла |
+
+Связанные классы:
+`DocsIndexingPipeline`, `DocsFactExtractor`, `DocsDocumentBuilder`
+
+### `D3_ENTITY_CATALOG`
+
+Задача:
+Хранит сущности, найденные в документации, чтобы искать документы и связи вокруг конкретной сущности.
+
+Формирование:
+Сущности извлекаются из frontmatter документа, после чего каждая сущность сохраняется отдельной записью.
+
+Фиксация в БД:
+| Атрибут в `metadata_json` | Описание | Источник |
+|---|---|---|
+| `entity_name` | имя сущности | `DocsEntityExtractor` |
+| `document_id` | идентификатор документа, где найдена сущность | `frontmatter.id`, иначе путь файла |
+| `document_type` | тип документа-источника | `frontmatter.type` |
+| `module` | модуль документа | `frontmatter.module` |
+| `domain` | домен документа | `frontmatter.domain` |
+| `subdomain` | поддомен документа | `frontmatter.subdomain` |
+| `tags` | теги документа или сущности | `frontmatter.tags` |
+| `source_path` | исходный путь документа | путь файла |
+
+Связанные классы:
+`DocsIndexingPipeline`, `DocsEntityExtractor`, `DocsDocumentBuilder`
+
+### `D4_WORKFLOW_INDEX`
+
+Задача:
+Хранит workflow и сценарии из документации для ответов про flow, шаги и жизненный цикл процесса.
+
+Формирование:
+Workflow извлекаются из detail sections документа и сохраняются как отдельные сценарии.
+Извлечение идет из структуры `Details -> ## Сценарий`.
+
+Фиксация в БД:
+| Атрибут в `metadata_json` | Описание | Источник |
+|---|---|---|
+| `workflow_id` | идентификатор сценария | вычисляется builder из названия, anchor и документа |
+| `document_id` | идентификатор документа-источника | `frontmatter.id`, иначе путь файла |
+| `workflow_name` | название сценария | блок `Details -> ## Сценарий -> **Название**` |
+| `preconditions` | предусловия сценария | блок `Details -> ## Сценарий -> **Предусловия**` |
+| `trigger` | триггер или событие запуска | блок `Details -> ## Сценарий -> **Триггер**` |
+| `main_flow` | основной сценарий | блок `Details -> ## Сценарий -> **Основной сценарий**` |
+| `alternative_flow` | альтернативные ветки | блок `Details -> ## Сценарий -> **Альтернативный сценарий**` |
+| `error_handling` | обработка ошибок | блок `Details -> ## Сценарий -> **Обработка ошибок**` |
+| `postconditions` | постусловия | блок `Details -> ## Сценарий -> **Постусловие**` |
+| `source_path` | исходный путь документа | путь файла |
+
+Связанные классы:
+`DocsIndexingPipeline`, `DocsWorkflowExtractor`, `DocsDocumentBuilder`
+
+### `D5_RELATION_GRAPH`
+
+Задача:
+Хранит связи между документами и сущностями документации для navigation и related docs retrieval.
+
+Формирование:
+Связи извлекаются из frontmatter и сохраняются как отдельные relation edges.
+
+Фиксация в БД:
+| Атрибут в `metadata_json` | Описание | Источник |
+|---|---|---|
+| `relation_id` | идентификатор связи | вычисляется builder из source, target, relation type и anchor |
+| `source_id` | источник связи | `frontmatter.id` или source документа в extractor |
+| `relation_type` | тип связи | `DocsRelationExtractor` |
+| `target_id` | целевой объект связи | `DocsRelationExtractor` |
+| `anchor` | место в документе, где обнаружена связь | `DocsRelationExtractor` |
+| `source_path` | исходный путь документа | путь файла |
+
+Связанные классы:
+`DocsIndexingPipeline`, `DocsRelationExtractor`, `DocsDocumentBuilder`
+
+### `D6_INTEGRATION_INDEX`
+
+Задача:
+Хранит прикладные интеграции компонента, API, UI, сущности или внешней системы.
+Используется для ответов на вопросы вида "какие интеграции есть у компонента".
+
+Формирование:
+Интеграции извлекаются из блока `## Integrations` документа.
+Одна интеграция должна превращаться в отдельную запись слоя.
+Описание интеграции может быть развернутым, а структурированные атрибуты должны выделяться в словарь.
+
+Фиксация в БД:
+| Атрибут в `metadata_json` | Описание | Источник |
+|---|---|---|
+| `integration_id` | идентификатор интеграции | вычисляется builder из source, target и anchor |
+| `source_id` | идентификатор объекта, для которого описана интеграция | `frontmatter.id` документа-источника |
+| `source_type` | тип исходного объекта | `frontmatter.doc_type` |
+| `target` | целевой объект интеграции | блок `## Integrations` |
+| `target_type` | тип целевого объекта, например `api`, `ui`, `entity`, `service`, `external_system` | блок `## Integrations` |
+| `direction` | направление интеграции | блок `## Integrations` |
+| `interaction` | тип взаимодействия | блок `## Integrations` |
+| `via` | технический канал интеграции | блок `## Integrations` |
+| `purpose` | назначение интеграции | блок `## Integrations` |
+| `details` | дополнительные атрибуты интеграции в виде словаря | блок `## Integrations` |
+| `domain` | домен документа | `frontmatter.domain` |
+| `subdomain` | поддомен документа | `frontmatter.subdomain` |
+| `source_path` | исходный путь документа | путь файла |
+| `anchor` | место в документе, где описана интеграция | блок `## Integrations` |
+
+Связанные классы:
+`DocsIndexingPipeline`, `DocsIntegrationExtractor`, `DocsDocumentBuilder`
+
+## Слои CODE
+
+### `C0_SOURCE_CHUNKS`
+
+Задача:
+Хранит фрагменты исходного кода как базовый слой для цитирования, explain и точечной догрузки кода.
+
+Формирование:
+Исходный файл режется на кодовые чанки, и для каждого чанка создается отдельная запись.
+
+Фиксация в БД:
+| Атрибут в `metadata_json` | Описание | Источник |
+|---|---|---|
+| `chunk_index` | порядковый номер чанка в файле | индекс чанка при нарезке |
+| `chunk_type` | тип чанка, например функция, класс или текстовый блок | `CodeTextChunker` |
+| `module_or_unit` | модуль, к которому относится chunk | вычисляется из пути файла |
+| `is_test` | признак тестового файла | `is_test_path(path)` |
+
+Связанные классы:
+`CodeIndexingPipeline`, `CodeTextChunker`, `CodeTextDocumentBuilder`
+
+### `C1_SYMBOL_CATALOG`
+
+Задача:
+Хранит символы кода: классы, функции и методы. Используется для поиска по именам и структуре кода.
+
+Формирование:
+Символы извлекаются `SymbolExtractor`, и каждый символ сохраняется как отдельная запись.
+
+Фиксация в БД:
+| Атрибут в `metadata_json` | Описание | Источник |
+|---|---|---|
+| `symbol_id` | идентификатор символа | `SymbolExtractor` |
+| `qname` | полное квалифицированное имя | `SymbolExtractor` |
+| `kind` | тип символа: класс, функция, метод | `SymbolExtractor` |
+| `signature` | сигнатура символа | `SymbolExtractor` |
+| `parent_symbol_id` | родительский символ | `SymbolExtractor` |
+| `package_or_module` | модуль или пакет символа | вычисляется из пути файла |
+| `is_test` | признак тестового файла | `is_test_path(path)` |
+
+Связанные классы:
+`CodeIndexingPipeline`, `PythonAstParser`, `SymbolExtractor`, `SymbolDocumentBuilder`
+
+### `C2_DEPENDENCY_GRAPH`
+
+Задача:
+Хранит связи между символами кода: вызовы, импорты, наследование. Используется для анализа зависимостей и flow.
+
+Формирование:
+Связи строятся `EdgeExtractor` по AST и списку символов, после чего каждая связь сохраняется отдельной записью.
+
+Фиксация в БД:
+| Атрибут в `metadata_json` | Описание | Источник |
+|---|---|---|
+| `edge_id` | идентификатор связи | `EdgeExtractor` |
+| `edge_type` | тип связи: вызов, импорт, наследование | `EdgeExtractor` |
+| `src_symbol_id` | исходный символ | `EdgeExtractor` |
+| `src_qname` | полное имя исходного символа | `EdgeExtractor` |
+| `dst_symbol_id` | целевой символ, если он разрешен | `EdgeExtractor` |
+| `dst_ref` | текстовая ссылка на целевой символ | `EdgeExtractor` |
+| `resolution` | статус разрешения связи | `EdgeExtractor` |
+| `is_test` | признак тестового файла | `is_test_path(path)` |
+
+Связанные классы:
+`CodeIndexingPipeline`, `EdgeExtractor`, `EdgeDocumentBuilder`
+
+### `C3_ENTRYPOINTS`
+
+Задача:
+Хранит точки входа приложения: HTTP routes, CLI commands и другие entrypoints.
+
+Формирование:
+Детекторы ищут HTTP и CLI точки входа по символам файла, после чего каждый найденный entrypoint сохраняется отдельной записью.
+
+Фиксация в БД:
+| Атрибут в `metadata_json` | Описание | Источник |
+|---|---|---|
+| `entry_id` | идентификатор точки входа | detector entrypoint model |
+| `entry_type` | тип точки входа | detector entrypoint model |
+| `framework` | framework, в котором найдена точка входа | detector entrypoint model |
+| `route_or_command` | route или команда | detector entrypoint model |
+| `handler_symbol_id` | идентификатор обработчика | detector entrypoint model |
+| `handler_symbol` | имя обработчика | detector entrypoint model |
+| `declaring_symbol` | символ, в котором объявлен entrypoint | detector entrypoint model |
+| `entrypoint_kind` | вид точки входа | detector entrypoint model |
+| `http_method` | HTTP-метод | detector entrypoint model |
+| `route_path` | путь маршрута | detector entrypoint model |
+| `decorator_text` | текст декоратора или объявления | detector entrypoint model |
+| `summary_text` | краткое описание точки входа | detector entrypoint model |
+| `is_test` | признак тестового файла | `is_test_path(path)` |
+| `lang_payload` | дополнительные данные детектора | detector metadata |
+| `artifact_type` | тип артефакта, здесь `CODE` | константа builder |
+
+Связанные классы:
+`CodeIndexingPipeline`, `EntrypointDetectorRegistry`, `FastApiEntrypointDetector`, `FlaskEntrypointDetector`, `TyperClickEntrypointDetector`, `EntrypointDocumentBuilder`
+
+### `C4_SEMANTIC_ROLES`
+
+Задача:
+Слой объявлен в enum и retrieval-планах как слой семантических ролей кода.
+
+Формирование:
+Слой формируется на основе символов, связей, dataflow slices и execution traces.
+В текущем runtime этот слой не используется как активный маршрут, так как домен `CODE` отключен.
+
+Фиксация в БД:
+Смысловые атрибуты слоя сохраняются в `rag_chunks.metadata_json`.
+Точное краткое описание состава этих атрибутов в текущем документе пока не зафиксировано.
+
+Связанные классы:
+`CodeIndexingPipeline`, `SemanticRoleBuilder`, `SemanticRoleDocumentBuilder`

_process/04. Analitycs artefacts.md

@@ -314,11 +314,71 @@ LLM не должна каждый раз тонуть в полном доку
 - функциональные требования;
 - UI;
 - API;
+- integrations;
 - ошибки;
 - НФТ;
 - связи;
 - кодовые привязки.
 
+### Блок `## Integrations`
+
+Если у объекта есть интеграции, они должны быть выделены в отдельный блок `## Integrations`.
+Интеграции не нужно дублировать во frontmatter.
+Основное описание хранится в body документа.
+
+Ожидаемый принцип:
+- одна интеграция = одна отдельная запись внутри блока;
+- у интеграции есть краткое имя;
+- у интеграции есть структурированные атрибуты;
+- дополнительные детали допускаются в свободной форме через вложенный словарь.
+
+Рекомендуемые атрибуты интеграции:
+- `target`
+- `target_type`
+- `direction`
+- `interaction`
+- `via`
+- `purpose`
+- `details`
+
+Где:
+- `target` - идентификатор или имя целевого объекта;
+- `target_type` - тип цели: `api`, `ui`, `entity`, `service`, `queue`, `db`, `external_system`;
+- `direction` - направление: `inbound`, `outbound`, `bidirectional`;
+- `interaction` - тип взаимодействия: `calls`, `reads`, `writes`, `emits`, `consumes`, `depends_on`;
+- `via` - технический канал интеграции;
+- `purpose` - зачем нужна интеграция;
+- `details` - словарь с гибкой структурой под дополнительные параметры.
+
+Пример:
+
+```md
+## Integrations
+
+### Orders API
+- target: api.orders.create
+- target_type: api
+- direction: outbound
+- interaction: calls
+- via: POST /api/orders
+- purpose: создание заказа
+- details:
+  - auth: service-token
+  - retry: true
+
+### Order Entity
+- target: domain.order
+- target_type: entity
+- direction: outbound
+- interaction: writes
+- via: repository
+- purpose: сохранение состояния заказа
+- details:
+  - transaction: required
+```
+
+Этот блок должен быть пригоден и для чтения человеком, и для последующего извлечения в отдельный RAG-слой интеграций.
+
 ## 1.10. Общие требования к markdown body
 
 1. В документе должен быть один `H1`, совпадающий с `title`.
@@ -428,6 +488,7 @@ UI-элементы должны храниться в **табличном** и
 ## Технический use case
 ## Функциональные требования
 ## Contract
+## Integrations
 ## Errors
 ## Нефункциональные требования
 ## Связанные блоки логики
@@ -454,6 +515,7 @@ UI-элементы должны храниться в **табличном** и
 ## Контекст
 ## Технический use case
 ## Функциональные требования
+## Integrations
 ## Ограничения и условия вызова
 ## Нефункциональные требования
 ## Связанные API / UI / integration points
@@ -787,4 +849,4 @@ DOCS и CROSS_DOMAIN остаются частью target architecture; в те
 - полноценные execution paths для всей системы;
 - богатые fact-индексы по всем доменам;
 - полный reference graph документации;
-- глубокая автоматизация подготовки системной аналитики.
+- глубокая автоматизация подготовки системной аналитики.

_process/05. MVP - process_v1.md

@@ -0,0 +1,100 @@
+# MVP: процесс v1
+
+## 1. Общее описание
+
+Запрос пользователя обрабатывается цепочкой API → рантайм агента → зарегистрированный процесс версии `v1` → один workflow из трёх последовательных шагов. Процесс **не** обращается к RAG и **не** маршрутизирует интенты: текст сообщения передаётся в LLM по фиксированному промпту. Ответ агента — результат генерации с лёгкой постобработкой (trim).
+
+```mermaid
+flowchart LR
+  subgraph api [API]
+    RS[RequestService]
+  end
+  subgraph runtime [Agent runtime]
+    AR[AgentRuntime]
+    PR[ProcessRunner]
+  end
+  subgraph v1 [Процесс v1]
+    P1[V1Process]
+    WG[V1FlowMainGraph]
+  end
+  subgraph wf [Workflow v1.flow_main]
+    S1[PrepareUserMessageStep]
+    S2[GenerateAnswerStep]
+    S3[FinalizeAnswerStep]
+  end
+  LLM[AgentLlmService]
+  RS --> AR
+  AR --> PR
+  PR --> P1
+  P1 --> WG
+  WG --> S1 --> S2 --> S3
+  S2 --> LLM
+```
+
+Клиент создаёт запрос с `process_version: v1`. `AgentRuntime` поднимает `RuntimeExecutionContext` (запрос, сессия, publisher, trace), выбирает `V1Process` из реестра и вызывает `run`. `V1Process` собирает `V1FlowContext` и прогоняет линейный граф: подготовка текста, один вызов LLM, финализация строки ответа. Итог попадает в `ProcessResult.answer` и дальше в ответ пользователю.
+
+---
+
+## 2. Шаги и контракты
+
+### 2.1. Вход в процесс: `V1Process.run`
+
+| | |
+|--|--|
+| **Название** | Запуск процесса v1 |
+| **Задача** | Собрать контекст workflow и выполнить граф до готового ответа. |
+| **Вход** | `RuntimeExecutionContext`: `request` (в т.ч. `message`), `session`, `publisher`, `trace`. |
+| **Выход** | `ProcessResult` с полем `answer: str`. |
+| **Как работает** | Создаётся `V1FlowContext` с `prompt_name` по умолчанию `v1_flow_main.answer`. Вызывается `V1FlowMainGraph.run`. Возвращается ответ из контекста workflow. |
+
+Код: `src/app/core/agent/processes/v1/process.py`.
+
+---
+
+### 2.2. Шаг workflow: `PrepareUserMessageStep`
+
+| | |
+|--|--|
+| **Название** | Подготовка сообщения пользователя |
+| **Задача** | Сформировать строку, которая уйдёт в LLM как пользовательский ввод. |
+| **Вход** | `V1FlowContext` с заполненным `runtime` и `prompt_name`. |
+| **Выход** | Тот же контекст с `prepared_message: str`. |
+| **Как работает** | Берётся `context.runtime.request.message` и обрезаются пробелы по краям (`strip`). Результат пишется в `prepared_message`. Других преобразований нет. |
+
+Код: `src/app/core/agent/processes/v1/workflow/flow_main/steps/prepare_user_message_step.py`.
+
+---
+
+### 2.3. Шаг workflow: `GenerateAnswerStep`
+
+| | |
+|--|--|
+| **Название** | Вызов LLM |
+| **Задача** | Сгенерировать ответ по выбранному промпту и подготовленному сообщению. |
+| **Вход** | `V1FlowContext` с `prepared_message`, `prompt_name`, `runtime.trace` для модуля LLM. |
+| **Выход** | Контекст с `answer: str` (сырой ответ модели). |
+| **Как работает** | Асинхронно в пуле потоков вызывается `AgentLlmService.generate(prompt_name, prepared_message, ...)`. В trace подключается модуль `workflow.v1.llm`. Идентификатор запроса передаётся в `log_context` для логов. |
+
+Код: `src/app/core/agent/processes/v1/workflow/flow_main/steps/generate_answer_step.py`.
+
+---
+
+### 2.4. Шаг workflow: `FinalizeAnswerStep`
+
+| | |
+|--|--|
+| **Название** | Финализация ответа |
+| **Задача** | Нормализовать строку ответа перед выдачей пользователю. |
+| **Вход** | `V1FlowContext` с заполненным `answer` после LLM. |
+| **Выход** | Контекст с обновлённым `answer`. |
+| **Как работает** | К ответу применяется `strip()` по краям. Другой логики нет. |
+
+Код: `src/app/core/agent/processes/v1/workflow/flow_main/steps/finalize_answer_step.py`.
+
+---
+
+### 2.5. Транспорт: `WorkflowGraph` (v1)
+
+Граф для v1 использует стандартный `WorkflowGraph`: на каждом шаге пишутся события `workflow_started`, `step_started`, `step_completed`, `workflow_completed` в `runtime_traces` через `context.runtime.trace`.
+
+Код: `src/app/core/agent/utils/workflow/graph.py`, обёртка `V1FlowMainGraph` в `src/app/core/agent/processes/v1/workflow/flow_main/graph.py`.

_process/05. MVP - process_v2.md

@@ -0,0 +1,220 @@
+# MVP: процесс v2
+
+## 1. Общее описание
+
+Процесс v2 в текущем MVP ориентирован в первую очередь на **документацию проекта**, но роутер также поддерживает `GENERAL / GENERAL_QA / SUMMARY` для общих обзорных вопросов. Для документных веток нужна активная RAG-сессия с проиндексированными документами.
+
+Это **узкий MVP**, а не полная target architecture. Поддерживаются три маршрута:
+
+- `GENERAL`
+- `GENERAL_QA`
+- `SUMMARY`
+- `DOCS`
+- `DOC_EXPLAIN`
+- `SUMMARY`
+- `FIND_FILES`
+
+Запрос проходит следующие смысловые этапы:
+
+1. проверка готовности сессии;
+2. intent routing;
+3. формирование retrieval-параметров;
+4. retrieval из `DOCS RAG`;
+5. минимальная сборка evidence;
+6. запуск task-focused workflow нужной ветки;
+7. формирование ответа.
+
+```mermaid
+flowchart TB
+  subgraph api [API]
+    RS[RequestService]
+  end
+  subgraph runtime [Agent runtime]
+    AR[AgentRuntime]
+    PR[ProcessRunner]
+  end
+  subgraph v2 [Процесс v2]
+    P2[V2Process]
+    IR[V2IntentRouter]
+    POL[V2RetrievalPolicyResolver]
+    AD[V2RagRetrievalAdapter]
+    RSR[RagSessionRetriever]
+    ASM[DocsEvidenceAssembler]
+  end
+  subgraph rag [Пакет rag]
+    RR[RagRepository]
+  end
+  subgraph wf [Workflow]
+    SUM[DocsExplainSummaryGraph]
+    FF[DocsExplainFindFilesGraph]
+  end
+  LLM[AgentLlmService]
+  RS --> AR --> PR --> P2
+  P2 --> IR --> POL --> AD --> RSR --> RR
+  AD --> ASM
+  ASM --> SUM
+  ASM --> FF
+  SUM --> LLM
+```
+
+Клиент указывает `process_version: v2`. Без `active_rag_session_id` в сессии процесс возвращает сообщение об ошибке. Иначе выполняется цепочка:
+
+маршрутизация → `RetrievalPlan` → retrieval строк из `DOCS RAG` → минимальная сборка evidence → ветвление по `subintent` → запуск workflow.
+
+### Реализованные домены, интенты и сабинтенты
+
+В коде заданы константы `V2Domain`, `V2Intent`, `V2Subintent`. Сейчас процесс intentionally ограничен одной рабочей областью.
+
+| Уровень | Значение (строка) | Реализация |
+|--------|-------------------|------------|
+| **Домен (routing_domain)** | `DOCS` | Единственный поддерживаемый домен: документация проекта. |
+| **Интент** | `DOC_EXPLAIN` | Единственный интент: объяснение по документации. |
+| **Сабинтент** | `SUMMARY` | Объяснение темы по SUMMARY-блокам документации. |
+| **Сабинтент** | `FIND_FILES` | Поиск путей к документам, где описана нужная сущность или тема. |
+
+Итого в текущем MVP реализована **одна** рабочая тройка домен×интент: `DOCS` + `DOC_EXPLAIN`, с **двумя** ветками по сабинтенту.
+
+---
+
+## 2. Этапы вне workflow (внутри `V2Process.run`)
+
+### 2.1. `V2IntentRouter.route`
+
+| | |
+|--|--|
+| **Название** | Маршрутизация запроса (v2) |
+| **Задача** | Определить домен, интент, subintent и извлечь якоря из текста. |
+| **Вход** | `user_query: str` (текст сообщения пользователя). |
+| **Выход** | `V2RouteResult`: `routing_domain`, `intent`, `subintent`, `user_query`, `normalized_query`, `target_terms`, `anchors` (`V2RouteAnchors`), `confidence`. |
+| **Как работает** | Router реализован по схеме **LLM-first**: `normalization` → `target_terms`/`anchors extraction` → `LLM router` → `deterministic validator` → `fallback`. LLM является **основным селектором маршрута**. Deterministic-слой больше не выбирает маршрут по умолчанию: он отвечает только за extraction, валидацию enum/комбинаций и fallback при сломанном или невалидном ответе LLM. В trace пишется событие `intent_routed`. |
+
+Код: `src/app/core/agent/processes/v2/intent_router/router.py`, `modules/normalizer.py`, `modules/target_terms.py`, `modules/anchors.py`, `routers/llm.py`, `routers/validator.py`, `routers/fallback.py`.
+
+---
+
+### 2.2. `V2RetrievalPolicyResolver.resolve`
+
+| | |
+|--|--|
+| **Название** | Политика retrieval для v2 |
+| **Задача** | По результату роутинга выбрать профиль, список слоёв RAG и лимит строк выдачи. |
+| **Вход** | `V2RouteResult`. |
+| **Выход** | `RetrievalPlan`: `profile`, `layers`, `limit`, опционально `filters`. |
+| **Как работает** | Это отдельный смысловой шаг между routing и retrieval. Он не ходит в БД и не извлекает данные, а только подготавливает параметры поиска. Для `FIND_FILES` выбирается один профиль слоёв и лимит, для `SUMMARY` — другой. Лог: `retrieval_plan_resolved`. |
+
+Код: `src/app/core/agent/processes/v2/retrieval/policy_resolver.py`.
+
+---
+
+### 2.3. `V2RagRetrievalAdapter` → `RagSessionRetriever.retrieve`
+
+| | |
+|--|--|
+| **Название** | Загрузка сырых строк из RAG по плану |
+| **Задача** | Делегировать поиск в единственную реализацию retrieval в пакете `rag`. |
+| **Вход** | `rag_session_id`, `query_text` (нормализованный запрос), `RetrievalPlan`. |
+| **Выход** | `list[dict]` — строки чанков в формате `RagRepository.retrieve` (поля `path`, `layer`, `metadata`, и т.д.). |
+| **Как работает** | Выполняется retrieval по уже сформированному плану: профиль, список слоёв и лимит. На этом шаге происходит только извлечение сырых строк из `DOCS RAG`. Лог: `rag_rows_fetched`. |
+
+Код адаптера: `src/app/core/agent/processes/v2/retrieval/v2_rag_adapter.py`.  
+Код API: `src/app/core/rag/retrieval/session_retriever.py`.
+
+---
+
+### 2.4. `DocsEvidenceAssembler`
+
+| | |
+|--|--|
+| **Название** | Сборка evidence для задачи |
+| **Задача** | Превратить сырые строки retrieval в списки summary или кандидатов файлов с дедупом и скорингом. |
+| **Вход** | Список строк `rows`, `V2RouteResult` (для `target_terms`). |
+| **Выход** | `list[RetrievedSummary]` или `list[RetrievedFile]`. |
+| **Как работает** | Это **минимальная evidence-проверка**, достаточная для MVP. Для `SUMMARY` отбрасываются записи без summary-текста и summary-like секции, затем применяется дедуп и простой скоринг по терминам. Для `FIND_FILES` остаются только релевантные пути документов, также с дедупом и простым скорингом. Здесь нет сложной многоступенчатой валидации: задача шага — отфильтровать очевидный шум и передать в workflow компактное evidence. Лог: `evidence_assembled`. |
+
+Код: `src/app/core/agent/processes/v2/evidence/assembler.py`.
+
+---
+
+## 3. Шаги workflow
+
+Текущие workflow являются **task-focused**: каждая ветка решает одну узкую прикладную задачу и не содержит общей универсальной логики для всех типов вопросов.
+
+### 3.1. Ветка `SUMMARY`: `GenerateSummaryAnswerStep`
+
+| | |
+|--|--|
+| **Название** | Сборка ответа по summary |
+| **Задача** | Сформировать ответ пользователю по найденным SUMMARY-блокам или сообщить об отсутствии. |
+| **Вход** | `DocsExplainSummaryContext`: `runtime`, `route`, `rag_session_id`, `prompt_name`, `documents` (список `RetrievedSummary`). |
+| **Выход** | Контекст с `answer: str`, `prompt_input` при успешном вызове LLM. |
+| **Как работает** | Workflow получает уже отобранные summary-документы. Если документов нет — возвращает честный fallback-ответ. Иначе собирает prompt input из запроса пользователя и найденных summary-блоков и вызывает LLM. Workflow не занимается retrieval и не строит retrieval-план: он решает только задачу генерации ответа по уже подготовленному evidence. |
+
+Код: `src/app/core/agent/processes/v2/workflows/docs_explain_summary/steps/generate_summary_answer_step.py`.  
+Граф: `DocsExplainSummaryGraph` (`V2WorkflowGraph`).
+
+---
+
+### 3.2. Ветка `FIND_FILES`: `FinalizeFindFilesAnswerStep`
+
+| | |
+|--|--|
+| **Название** | Сборка списка файлов |
+| **Задача** | Вывести пользователю markdown-список путей к файлам документации. |
+| **Вход** | `DocsExplainFindFilesContext`: `runtime`, `route`, `rag_session_id`, `files` (`RetrievedFile`). |
+| **Выход** | Контекст с `answer: str`. |
+| **Как работает** | Workflow получает уже собранный список файлов и формирует финальный ответ. Если файлов нет — возвращает fallback. Если файлы есть — отдает детерминированный список путей. Эта ветка intentionally не использует LLM, потому что задача сводится к выдаче путей, а не к генерации объяснения. |
+
+Код: `src/app/core/agent/processes/v2/workflows/docs_explain_find_files/steps/finalize_find_files_answer_step.py`.  
+Граф: `DocsExplainFindFilesGraph` (`V2WorkflowGraph`).
+
+---
+
+### 3.3. Транспорт: `V2WorkflowGraph`
+
+| | |
+|--|--|
+| **Название** | Workflow v2 с буфером trace |
+| **Задача** | Выполнить шаги без пошаговых `step_started`/`step_completed` в trace; один раз сбросить сводку. |
+| **Вход** | Контекст workflow (`DocsExplainSummaryContext` или `DocsExplainFindFilesContext`). |
+| **Выход** | Обновлённый контекст. |
+| **Как работает** | Для каждого шага: `trace_input` до `run`, затем `run`, затем `trace_output`; записи копятся в список. В trace уходят `workflow_started`, затем `workflow_trace_flushed` с массивом шагов, затем `workflow_completed`. Статусы пользователю публикуются через `publisher` как и раньше. |
+
+Код: `src/app/core/agent/processes/v2/workflows/v2_workflow_graph.py`.
+
+---
+
+## 4. Сборка в приложении
+
+В `ModularApplication` создаются `RagSessionRetriever`, `V2RagRetrievalAdapter`, `V2RetrievalPolicyResolver`, `DocsEvidenceAssembler` и передаются в `V2Process` (см. `src/app/core/application.py`).
+
+---
+
+## 5. Итоговая концептуальная схема текущего MVP
+
+В концептуальном виде текущий `v2` работает так:
+
+1. **Session check**
+   Проверка, что есть активная RAG-сессия проекта.
+
+2. **LLM-first intent routing**
+   Нормализация, extraction (`target_terms`, `anchors`), затем основной выбор маршрута через LLM.
+
+3. **Deterministic validation + fallback**
+   Проверка enum/комбинации маршрута и fallback только если LLM не ответил или вернул невалидный маршрут.
+
+4. **Retrieval parameter planning**
+   Формирование профиля поиска, слоёв и лимитов.
+
+5. **RAG retrieval**
+   Загрузка сырых строк из `DOCS RAG`.
+
+6. **Minimal evidence assembly**
+   Дедуп, базовый скоринг, отбор полезных summary или файлов.
+
+7. **Task-focused workflow**
+   Узкая ветка `SUMMARY` или `FIND_FILES`.
+
+8. **Final response**
+   Либо explanation через LLM, либо детерминированный список файлов.
+
+Это и есть актуальная архитектура **узкого MVP**, синхронизированная с текущей реализацией.

_process/components/v2_intent_router_architecture.md

@@ -0,0 +1,269 @@
+# V2IntentRouter Architecture
+
+## 1. Архитектура
+
+Текущий `V2IntentRouter` состоит из следующих компонентов:
+
+- `router.py`
+  Главная точка входа и оркестратор.
+
+- `modules/normalizer.py`
+  Нормализация текста запроса в `normalized_query`.
+
+- `modules/target_terms.py`
+  Извлечение `target_terms`, `endpoint_paths`, `matched_aliases`, `alias_docs`.
+
+- `modules/anchors.py`
+  Извлечение `anchors` и вспомогательных marker-сигналов.
+
+- `routers/docs_subintent_resolver.py`
+  Определение `subintent`.
+
+- `routers/deterministic.py`
+  Детерминированное определение `routing_domain`, `intent`, `subintent`, `confidence`, `routing_mode`, `llm_router_used`, `reason_short`.
+
+- `routers/llm.py`
+  LLM-based определение `routing_domain`, `intent`, `subintent`, `confidence`, `reason_short`.
+
+- `routers/prompts.yml`
+  Prompt для LLM-router.
+
+## 2. Контракт
+
+### Вход
+
+- `user_query: str`
+
+### Выход
+
+`V2RouteResult`:
+
+- `routing_domain: str`
+- `intent: str`
+- `subintent: str`
+- `user_query: str`
+- `normalized_query: str`
+- `target_terms: list[str]`
+- `anchors: V2RouteAnchors`
+- `confidence: float`
+- `routing_mode: str`
+- `llm_router_used: bool`
+- `reason_short: str`
+
+`V2RouteAnchors`:
+
+- `entity_names: list[str]`
+- `terms: list[str]`
+- `file_names: list[str]`
+- `endpoint_paths: list[str]`
+- `target_doc_hints: list[str]`
+- `matched_aliases: list[str]`
+- `process_domain: str | None`
+- `process_subdomain: str | None`
+
+## 3. Поддерживаемые домены, интенты и сабинтенты
+
+### Домены
+
+- `DOCS`
+- `GENERAL`
+
+### Интенты
+
+- `DOC_EXPLAIN`
+- `GENERAL_QA`
+
+### Сабинтенты
+
+- `SUMMARY`
+- `FIND_FILES`
+
+### Поддерживаемые маршруты
+
+- `GENERAL / GENERAL_QA / SUMMARY`
+- `DOCS / DOC_EXPLAIN / SUMMARY`
+- `DOCS / DOC_EXPLAIN / FIND_FILES`
+
+## 4. Флоу обработки запроса
+
+1. `router.py` принимает `user_query`.
+2. `modules/normalizer.py` строит `normalized_query`.
+3. `modules/target_terms.py` извлекает ключевые термы и alias-based сигналы.
+4. `modules/anchors.py` строит `anchors` и marker-сигналы.
+5. `router.py` собирает `QueryFeatures`.
+6. `routers/deterministic.py` пытается определить маршрут детерминированно.
+7. Если deterministic route найден, он сразу возвращается.
+8. Если deterministic route не найден, `router.py` вызывает `routers/llm.py`.
+9. Если LLM вернул валидный маршрут, собирается `V2RouteResult` с `routing_mode="llm_assisted"`.
+10. Если LLM недоступен или не вернул валидный маршрут, используется fallback:
+    `GENERAL / GENERAL_QA / SUMMARY` с `routing_mode="llm_fallback"`.
+
+## 5. Компоненты по флоу
+
+### `router.py`
+
+- Задача
+  Собрать весь процесс роутинга в одной входной точке.
+
+- Как решает
+  Последовательно вызывает normalizer, target terms extractor, anchors extractor, deterministic router и при необходимости LLM router.
+
+- Вход
+  `user_query: str`
+
+- Выход
+  `V2RouteResult`
+
+### `modules/normalizer.py`
+
+- Задача
+  Привести запрос к стабильной форме для дальнейшего анализа.
+
+- Как решает
+  Схлопывает лишние пробелы через `" ".join(...split())`.
+
+- Вход
+  `user_query: str`
+
+- Выход
+  `normalized_query: str`
+
+### `modules/target_terms.py`
+
+- Задача
+  Выделить ключевые термы и retrieval-сигналы из запроса.
+
+- Как решает
+  Использует:
+  - regex для path/entity-like фрагментов
+  - список stop-words
+  - alias rules с фразами и каноническими термами
+  - эвристику для `/health`
+
+- Вход
+  `normalized_query: str`
+
+- Выход
+  `TargetTermsAnalysis`:
+  - `target_terms`
+  - `endpoint_paths`
+  - `matched_aliases`
+  - `alias_docs`
+
+### `modules/anchors.py`
+
+- Задача
+  Построить полный набор `anchors` и doc-oriented marker-сигналов.
+
+- Как решает
+  Использует:
+  - regex для `entity_names` и `file_names`
+  - словари marker-фраз:
+    - file markers
+    - architecture markers
+    - logic markers
+    - domain markers
+    - endpoint markers
+  - map `endpoint -> target_doc_hint`
+  - alias docs из `TargetTermsAnalysis`
+
+- Вход
+  - `normalized_query: str`
+  - `TargetTermsAnalysis`
+
+- Выход
+  `AnchorAnalysis`:
+  - `anchors`
+  - `file_markers`
+  - `architecture_markers`
+  - `logic_markers`
+  - `domain_markers`
+  - `endpoint_markers`
+
+### `routers/docs_subintent_resolver.py`
+
+- Задача
+  Определить `subintent`.
+
+- Как решает
+  Эвристика:
+  - если есть `file_markers` -> `FIND_FILES`
+  - если есть doc-signals (`endpoint_paths`, `endpoint_markers`, `architecture_markers`, `logic_markers`, `domain_markers`, `target_doc_hints`) -> `SUMMARY`
+  - иначе `None`
+
+- Вход
+  `QueryFeatures`
+
+- Выход
+  `subintent: str | None`
+
+### `routers/deterministic.py`
+
+- Задача
+  Детерминированно определить маршрут без LLM там, где это возможно.
+
+- Как решает
+  Использует:
+  - `DocsSubintentResolver`
+  - проверку conflicting doc anchors
+  - список general markers
+
+  Правила:
+  - `FIND_FILES` -> `DOCS / DOC_EXPLAIN / FIND_FILES`
+  - `subintent != None` и нет конфликта doc-signals -> `DOCS / DOC_EXPLAIN / SUMMARY`
+  - general marker -> `GENERAL / GENERAL_QA / SUMMARY`
+
+- Вход
+  - `user_query: str`
+  - `QueryFeatures`
+  - `anchors: V2RouteAnchors`
+
+- Выход
+  `V2RouteResult | None`
+
+### `routers/llm.py`
+
+- Задача
+  Определить маршрут через LLM, если deterministic routing не дал результата.
+
+- Как решает
+  Формирует JSON payload из:
+  - `user_query`
+  - `normalized_query`
+  - `target_terms`
+  - `anchors`
+  - списка допустимых маршрутов
+
+  Затем:
+  - вызывает LLM
+  - парсит JSON
+  - валидирует маршрут по whitelist
+  - нормализует `confidence`
+
+- Вход
+  - `user_query: str`
+  - `normalized_query: str`
+  - `target_terms: list[str]`
+  - `anchors: dict`
+
+- Выход
+  `dict | None`:
+  - `routing_domain`
+  - `intent`
+  - `subintent`
+  - `confidence`
+  - `reason_short`
+
+### `routers/prompts.yml`
+
+- Задача
+  Задать LLM-router формальный контракт ответа.
+
+- Как решает
+  Описывает допустимые маршруты и требует вернуть только JSON.
+
+- Вход
+  Payload от `routers/llm.py`
+
+- Выход
+  Структурированный JSON-ответ LLM