agent/v1_plan.md

# v1.plan.md

## 1. Цель ближайшего этапа

На ближайшем этапе цель — не достраивать полного агента и не интегрировать решение в UI, а довести до зрелого состояния **изолированный code-first test pipeline**:

**user query -> IntentRouterV2 -> retrieval plan -> layered retrieval -> evidence gate -> LLM answer -> diagnostics**

Именно этот контур должен стать будущим ядром агента, которое позже заменит legacy `RouterService`.

---

## 2. Что считается результатом этапа

Этап можно считать успешным, когда:

- `IntentRouterV2` стабильно определяет `intent`, `sub_intent`, `keyword_hints`, `path_scope`, `layers`, `conversation_mode` и retrieval constraints;
- retrieval реально следует плану, заданному роутером;
- LLM получает контекст, собранный из retrieval, а не из побочных обходных механизмов;
- ответ не строится без достаточного evidence;
- диагностика тестов позволяет понять:
  - что выбрал router;
  - что извлек retrieval;
  - чего не хватило;
  - почему ответ хороший или плохой.

---

## 3. Что сейчас не делать

На текущем этапе не стоит:

- встраивать это сразу в UI;
- подключать docs retrieval как обязательную часть MVP;
- строить полный cross-domain runtime;
- пытаться довести сразу весь orchestration runtime;
- инвестировать много времени в `C6`, `D5`, `D6`;
- лечить legacy `RouterService`, кроме минимально необходимого для совместимости.

---

## 4. Приоритетный план работ

## 4.1. Итерация 1 — зафиксировать канонический test-first контур

### 4.1.1. Принять `IntentRouterV2` как единственную точку истины для тестового MVP

Именно `IntentRouterV2` должен определять:

- `domain`
- `intent`
- `sub_intent`
- `keyword_hints`
- `path_scope`
- `layers`
- `conversation_mode`
- retrieval constraints

### 4.1.2. Зафиксировать минимальный набор сценариев MVP-now

Для текущего этапа в качестве канонического набора сценариев следует оставить:

- `OPEN_FILE`
- `EXPLAIN`
- `FIND_TESTS`
- `FIND_ENTRYPOINTS`
- `GENERAL_QA` как fallback

### 4.1.3. Зафиксировать контракт тестового пайплайна

Нужно явно определить структуру следующих объектов:

- `RouterResult`
- `RetrievalRequest`
- `RetrievalResult`
- `EvidenceBundle`
- `AnswerSynthesisInput`
- `DiagnosticsReport`

Это нужно, чтобы тесты настраивали устойчивый контракт, а не размытый процесс.

---

## 4.2. Итерация 2 — связать router и retrieval

### 4.2.1. Сделать retrieval adapter под контракт роутера

Output `IntentRouterV2` должен напрямую превращаться в retrieval plan.

Примеры:

- `OPEN_FILE`
  - path-priority retrieval
  - `C0_SOURCE_CHUNKS`

- `EXPLAIN`
  - symbol-first retrieval
  - `C1 + C0 + C2`, optionally `C3`

- `FIND_TESTS`
  - target symbol / path
  - lightweight `C5-lite`

- `FIND_ENTRYPOINTS`
  - `C3_ENTRYPOINTS`

- `GENERAL_QA`
  - ограниченный broad retrieval без агрессивных допущений

### 4.2.2. Убрать разрыв между индексатором и retrieval runtime

Нужна надежная связка:

**index data -> retrieval gateway -> normalized retrieval output**

Retrieval должен стать нормальной runtime-функцией, а не только наличием индексов и отдельных explain-механизмов.

### 4.2.3. Ввести единый формат retrieval output

Нужен единый формат, в который складываются найденные артефакты:

- symbols
- chunks
- relations
- entrypoints
- tests
- diagnostics per layer

Это станет основой для `EvidenceBundle`.

---

## 4.3. Итерация 3 — перенести evidence-first логику в общий test pipeline

### 4.3.1. Сделать общий evidence gate

Для каждого sub-intent нужно определить minimum evidence.

#### `OPEN_FILE`
- найден path или очень сильный lexical hit;
- есть хотя бы 1–2 relevant chunks.

#### `EXPLAIN`
- найден целевой symbol или уверенный target fragment;
- есть минимальное число code chunks;
- есть хотя бы базовые relations или surrounding context.

#### `FIND_TESTS`
- найден target symbol/file;
- найден хотя бы один reliable candidate test.

#### `FIND_ENTRYPOINTS`
- найден хотя бы один candidate entrypoint.

#### `GENERAL_QA`
- найден хоть какой-то устойчивый контекст;
- иначе ответ должен честно говорить о слабом evidence.

### 4.3.2. Запретить уверенный ответ без опоры

Если minimum evidence не выполнен, система должна:

- либо честно деградировать;
- либо выдать частичный ответ;
- либо явно сообщить, каких данных не хватает.

---

## 4.4. Итерация 4 — унифицировать сборку контекста для LLM

### 4.4.1. Ввести единый `EvidenceBundle`

LLM должна получать структурированный пакет:

- target intent / sub-intent
- target symbol / path
- relevant code chunks
- retrieved relations
- entrypoints if any
- test evidence if any
- retrieval diagnostics summary
- evidence sufficiency flags

### 4.4.2. Разделить fast context и deep context

#### Fast context
Короткая выжимка:
- target symbol
- file
- short relations summary
- top evidence

#### Deep context
Полные chunks, расширенные relations и supporting fragments.

### 4.4.3. Стандартизировать prompt contract

Для каждого sub-intent нужен понятный режим ответа:

- открыть;
- объяснить;
- найти тесты;
- найти точки входа;
- общий fallback.

LLM должна понимать:

- какой тип ответа нужен;
- насколько evidence полон;
- можно ли делать выводы;
- где надо явно отметить неопределенность.

---

## 4.5. Итерация 5 — довести диагностику до рабочего инструмента настройки

### 4.5.1. Разделить диагностику на 2 уровня

#### Уровень 1 — Human-readable summary
Коротко:
- intent выбран правильно / нет;
- target найден / нет;
- retrieval успешен / нет;
- evidence достаточен / нет;
- ответ надежный / частичный / слабый.

#### Уровень 2 — Detailed diagnostics
Подробно:
- router fields;
- layer-by-layer retrieval;
- empty / failed layers;
- ranking decisions;
- evidence gate results;
- context assembly details.

### 4.5.2. Добавить явные failure reasons

Рекомендуемый минимальный набор:

- `router_low_confidence`
- `target_symbol_not_found`
- `path_scope_empty`
- `layer_c1_empty`
- `layer_c2_empty`
- `test_mapping_not_found`
- `insufficient_code_evidence`

---

## 5. Как трактовать RAG-план на текущем этапе

## 5.1. Что оставить как целевой план

Целевую карту слоев оставляем без изменений:

- `C0–C6`
- `D0–D6`

Она остается правильной как target architecture.

## 5.2. Что считать MVP-now

Для текущего этапа обязательны:

- `C0_SOURCE_CHUNKS`
- `C1_SYMBOL_CATALOG`
- `C2_SYMBOL_RELATIONS`
- `C3_ENTRYPOINTS`

И в облегченном виде:

- `C5_TEST_MAPPINGS_LITE`

Пока не делать блокирующими:

- `C4_EXECUTION_PATHS`
- `C6_CODE_FACTS`
- весь docs runtime

## 5.3. Что считать следующим этапом

После стабилизации code-first MVP:

- подключение docs retrieval;
- использование D-layers в runtime;
- docs-from-code generation;
- cross-domain linking.

---

## 6. Как строить тестовый контур

## 6.1. Router tests

Проверяют только:

- intent
- sub_intent
- layers
- keyword_hints
- path_scope
- confidence / fallback behavior

## 6.2. Retrieval tests

Проверяют:

- что retrieval реально использует router output;
- какие слои сработали;
- что извлечено;
- нет ли шума от тестов;
- не пропал ли основной код.

## 6.3. Evidence gate tests

Проверяют:

- достаточен ли evidence;
- правильно ли система деградирует;
- не отвечает ли уверенно при слабой опоре.

## 6.4. Answer quality tests

Проверяют финальный ответ LLM:

- есть ли опора в коде;
- нет ли лишних догадок;
- хватает ли связности;
- соответствует ли ответ типу вопроса.

---

## 7. Что скорректировать в README / архитектурном плане

В README нужно явно разделить:

### 7.1. Target Architecture
Полная целевая система.

### 7.2. MVP-now
Изолированный test-first контур для `CODE_QA`, который:

- не зависит от UI;
- не зависит от full runtime orchestration;
- нацелен на доводку `IntentRouterV2` + retrieval + evidence + LLM answers.

---

## 8. Самые важные изменения в реализации прямо сейчас

Приоритет:

### P1
Сделать `IntentRouterV2` центром тестового MVP.

### P2
Связать router output с реальным layered retrieval.

### P3
Ввести единый `EvidenceBundle`.

### P4
Сделать общий evidence gate для всего test pipeline.

### P5
Привести диагностику к форме, удобной для настройки через тесты.

### P6
Добавить `C5-lite` для `FIND_TESTS`.

---

## 9. Итоговая формулировка ближайшей цели

> Довести до зрелости изолированный code-first test pipeline на базе `IntentRouterV2`, в котором роутер управляет retrieval, retrieval формирует evidence bundle, evidence gate контролирует достаточность опоры, а LLM отвечает строго на основе извлеченного контекста и прозрачной диагностики.