
# ТЗ Этап 1

## Foundation Hardening для Assistant Mode

## 0. Смысл этапа

Этот этап **не должен** строить взрослую финальную архитектуру.
Он должен сделать другое:

**превратить текущий explainable routed assistant из “формально работающего контура” в устойчивый базовый слой, на который уже можно ставить problem-cluster retrieval, lifecycle formalization и investigation engine.**

То есть задача этапа не “улучшить ответы вообще”, а:

* убрать самые опасные архитектурные слабости текущего слоя;
* перестать терять предмет анализа между шагами;
* перестать собирать слишком широкие broad answers;
* перестать генерировать explanation, в котором есть labels, но нет механики;
* ввести измеримость качества именно с точки зрения бухгалтера.

---

# 1. От чего идём: целевая способность системы

Если смотреть от финальной цели назад, то уже на первом этапе система должна приобрести **четыре базовые способности**, без которых всё дальнейшее бессмысленно.

### 1. Удержание предмета расследования

Система должна помнить не только историю чата, а **что именно сейчас проверяется**, какие гипотезы открыты, какие сущности уже подняты, какой период и какой контур в фокусе.

Сейчас этого нет: conversation memory есть, investigation memory model отсутствует.

### 2. Сужение broad-вопросов до управляемого бухгалтерского профиля

Система должна перестать считать успехом ситуацию, когда generic chain query narrowed “формально”, но по факту остался почти весь датасет. Это уже подтверждено на текущем контуре: для explicit account scope narrowing сильное, а для generic cross-entity prompts всё ещё слишком широкое.

### 3. Поднятие механики проблемы в retrieval result

LLM сейчас получает normalizer output, route summary, normalized retrieval payload и grounding/coverage diagnostics. Но explanation остаётся generic именно потому, что retrieval evidence ещё недостаточно механизмоспецифичен.
На первом этапе надо не “сделать тексты красивее”, а поднять вверх поля, из которых можно строить конкретное объяснение.

### 4. Переход от технической оценки к бухгалтерской полезности

Сейчас меряется technical pipeline quality, но accountant-facing utility metrics ещё неполные. Это нужно закрыть именно сейчас, иначе дальше система будет “развиваться” по ложным индикаторам.

---

# 2. Что сохраняем, а что меняем

## 2.1. Что сохраняем без архитектурного слома

Ниже то, что на первом этапе **не переписываем**, а используем как базу:

* существующий assistant loop;
* deterministic routing summary;
* normalizer pipeline `normalizer_v2_0_2`;
* explainable contract (`requirements`, `coverage_report`, `answer_grounding_check`);
* semantic retrieval profile в `executeHybrid`;
* debug drawer;
* session-scoped conversation continuity;
* route set (`store_feature_risk`, `hybrid_store_plus_live`, `batch_refresh_then_store`, `store_canonical`, `live_mcp_drilldown`).

Это важно: Этап 1 не должен устроить архитектурную ломку.
Он должен **усилить текущий контур**, а не заменить его “идеальной системой”.

---

## 2.2. Что меняем принципиально

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

1. retrieval policy for broad/generic prompts
2. retrieval result schema
3. answer synthesis policy
4. session model
5. eval layer
6. decomposition guardrail для noisy/translit и multi-intent compression

---

## 2.3. От чего сознательно отказываемся на этапе 1

На этом этапе **не строим**:

* полноценный ontology graph;
* полноценный lifecycle engine;
* полноценный investigation orchestrator;
* полноценный live verification bridge;
* финальный problem-cluster retrieval как default unit.

Это всё уже названо как следующий архитектурный слой, но не как ближайший P0.

Но:

* подготавливаем данные и контракты под эти сущности;
* убираем то, что потом будет мешать их внедрению;
* не пишем времянки, противоречащие target architecture.

---

# 3. Архитектурная цель этапа 1

К концу этапа текущая система должна перейти из состояния:

**“работающий explainable routed assistant с semantic narrowing upgrade”**

в состояние:

**“устойчивый accountant-facing assistant baseline с session investigation state, усиленным narrowing, mechanism-aware evidence pack и предметными метриками качества”**

---

# 4. Главные сущности этапа 1

Теперь по сущностям — не просто перечисление, а **что с ними делаем и зачем**.

---

## 4.1. Сущность №1 — `investigation_state`

### Почему она нужна

Сейчас в системе есть session conversation, но нет модели расследования. Это прямо зафиксировано как архитектурный пробел.
Из-за этого follow-up может быть связным по чату, но не становится настоящим продолжением анализа.

### Что не устраивает в текущем состоянии

Текущая session memory:

* хранит историю сообщений;
* пригодна для continuity;
* непригодна для hypothesis-driven analysis.

Это и есть разрыв между “чатом” и “расследованием”.

### Что делаем

Вводим новый слой session model: `investigation_state`.

### Что именно должно появиться

Минимальная сущность должна включать:

* `session_id`
* `focus`

  * domain
  * period
  * primary_accounts
  * active_query_subject
* `active_entities`
* `open_hypotheses`
* `checked_hypotheses`
* `branches`
* `resolved_findings`
* `unresolved_findings`
* `next_actions`
* `evidence_summary`
* `working_assumptions`
* `query_mode_hint` (`direct_answer` / `investigation_candidate`)

Базовый schema direction уже есть в отчёте, но на этапе 1 его надо превратить из спецификации в рабочий backend contract. 

### Что не делаем пока

Не строим полный branch engine и не запускаем автоматическое исследование соседних веток как policy standard. Это следующий слой. Сейчас фиксируем **контейнер состояния**, а не весь investigation orchestrator. 

### Что это даст

* follow-up перестанет быть просто ещё одним запросом;
* broad causal questions можно будет удерживать внутри одного аналитического контекста;
* позже сюда без боли встанет hypothesis tracking.

---

## 4.2. Сущность №2 — `semantic_retrieval_profile` (усиление, не замена)

### Почему она нужна

Она уже есть и уже улучшила retrieval, особенно на explicit accounting scope. Но generic prompts всё ещё narrowing’ятся слишком слабо.

### Что не устраивает

Профиль пока:

* лучше старого GUID-or-full-scan;
* но ещё недостаточно жёсткий на широких вопросах;
* не всегда переводит broad chain query в достаточно узкий бухгалтерский поиск.

### Что делаем

Не переписываем профиль заново, а вводим **mandatory narrowing policy** для проблемных классов запросов.

### Что добавляем в профиль как обязательные рабочие поля

Сейчас у вас уже есть account/domain/document/relation/anomaly intersections. На первом этапе надо зафиксировать обязательные блоки:

* `query_subject`
* `account_scope`
* `domain_scope`
* `document_types`
* `entity_types`
* `relation_patterns`
* `anomaly_patterns`
* `ranking_basis`
* `explanation_focus`
* `minimum_evidence_requirements`
* `broad_query_guard`
* `scope_confidence`

### Что меняем в логике

Если query broad и нет явного account scope, retrieval **не имеет права** просто сделать “semantic narrowing = true” и оставить 242 из 262.
Он должен пройти через guardrail policy:

1. попытка достроить предметный scope из:

   * session focus
   * domain hints
   * document hints
   * relation hints
2. если после этого narrowing всё ещё рыхлый:

   * понизить confidence,
   * пометить result как broad,
   * ограничить final answer depth,
   * предложить controlled clarification или drilldown direction.

### То, от чего отказываемся

От практики считать успешным любой routed answer, где technically есть profile и narrowing flag. Это ложный индикатор качества.

### Что это даст

* меньше pseudo-relevant broad answers;
* меньше одинаковых или слишком похожих выдач;
* более честная работа с low-specificity prompts.

---

## 4.3. Сущность №3 — `mechanism-aware evidence pack`

### Почему нужна

В отчёте уже сказано, что explanation generic из-за broad retrieval unit и limited mechanism-specific fields.
То есть проблема не в том, что composer не умеет писать, а в том, что наверх приходит недостаточно причинной информации.

### Что не устраивает сейчас

Сейчас evidence часто выглядит как:

* risk factors,
* labels,
* selection reasons общего типа,
* business interpretation шаблонного характера.

Из-за этого ответ может быть структурно правильным, но семантически слабым. Это видно и по логам: там уже есть “broken_lifecycle”, “posting_mismatch”, “cross_domain_inconsistency”, но эти признаки ещё не собираются в конкретный механизм поломки.

### Что делаем

Для `hybrid_store_plus_live` и `store_feature_risk` вводим обязательный `mechanism-aware evidence pack`.

### Какие поля должны появиться у top item

Не на уровне идеальной графовой модели, а на текущем data contour:

* `mechanism_of_failure`
* `failed_expected_edge`
* `expected_next_step`
* `actual_detected_step`
* `mechanism_confidence`
* `affected_documents`
* `affected_postings`
* `affected_accounts`
* `period_impact_hint`
* `business_defect_class`
* `requires_neighbor_check`
* `is_snapshot_limited`

### Пример логики

Не просто:

* `broken_lifecycle`

А:

* expected_next_step = “settlement closure by linked calculation document”
* actual_detected_step = “payment reflected, linked closure path not confirmed”
* failed_expected_edge = “statement_to_document -> settlement closure”
* mechanism_of_failure = “payment recorded without confirmed closure in expected chain”

### Что сохраняем

Risk labels остаются, но становятся вторичным слоем, а не единственным объясняющим слоем.

### Что это даст

* composer получит материал для case-specific explanation;
* даже без ontology graph ответы станут более предметными;
* станет видно, где retrieval реально понимает механизм, а где нет.

---

## 4.4. Сущность №4 — `answer contract v1.1`

### Почему нужна

Формально explainable contract уже реализован. Но user-facing ответы всё ещё могут быть generic и слишком top-entity-heavy.

### Что не устраивает

Текущие ответы:

* лучше, чем раньше;
* но всё ещё часто объясняют “по какому профилю искали”, а не “что именно сломано”.

### Что делаем

Не переписываем composer с нуля.
Меняем policy сборки ответа.

### Новый принцип

Ответ должен строиться в следующем порядке:

1. **что именно найдено**
2. **что именно в этом проблемно**
3. **какой механизм поломки предполагается**
4. **на чём это основано**
5. **какие документы/связи это подтверждают**
6. **что ограничивает вывод**
7. **что проверить дальше**

А не так:

* какой route,
* какой profile,
* какие labels.

### Что меняем в сборке

Для problem/explanation answers composer обязан:

* использовать `mechanism_of_failure` как главный narrative anchor;
* использовать `affected_documents` как конкретные опорные объекты;
* понижать уверенность, если есть только labels без mechanism;
* не выстраивать top narrative вокруг counterparty count, если вопрос не про ranking контрагентов.

### От чего отказываемся

От generic text scaffolding вроде:

* “результат отражает структурные признаки разрыва цепочки”
* “объекты приоритетны для проверки”
  если за этим не следует конкретный case.

Именно это сейчас делает ответы убедительнее внешне, чем они есть по сути.

### Что это даст

Даже без нового retrieval unit ответы уже перестанут быть purely decorative.

---

## 4.5. Сущность №5 — `decomposition guardrail`

### Почему нужна

Тонкая multi-requirement структура всё ещё может compress’иться, noisy/translit input может терять intent quality. Это уже зафиксировано.

### Что не устраивает

Даже если routing и retrieval сильнее, пользовательский вопрос может быть испорчен на раннем этапе:

* часть требований схлопнулась;
* важная гипотеза потерялась;
* транслит или бытовая бухгалтерская формулировка испортили intent.

### Что делаем

Добавляем не новый LLM-слой, а **guardrail around decomposition**.

### Что должно появиться

1. pre-normalization alias layer:

   * транслит,
   * бытовые бухгалтерские выражения,
   * alias dictionary
2. multi-requirement preservation rule:

   * если в вопросе обнаружено несколько смысловых действий, planner не имеет права silently compress их в один fragment без отметки потери
3. decomposition quality flag:

   * `high`
   * `soft_assumptions_used`
   * `intent_loss_risk`
   * `clarification_recommended`

### От чего отказываемся

От негласной практики “если route найден, значит декомпозиция достаточная”.

### Что это даст

* меньше ложных “зелёных” обработок;
* больше честности там, где вопрос реально разобран не полностью;
* меньше false out_of_scope и ложных soft assumptions.

---

## 4.6. Сущность №6 — `accountant eval layer`

### Почему нужна

Сейчас pipeline quality меряется, а accountant-facing utility metrics ещё нет в завершённом виде. Это уже признано P0.

### Что не устраивает

Пока нет правильной оценки, команда может улучшать то, что не даёт реальной ценности бухгалтеру.

### Что делаем

Строим evaluation layer именно под user value.

### Обязательные метрики этапа 1

1. `retrieval_differentiation_rate`
2. `generic_explanation_rate`
3. `accountant_actionability_score`
4. `false_confidence_rate`
5. `broad_answer_rate`
6. `mechanism_specificity_score`
7. `followup_context_retention_score`

Первые четыре уже названы в отчёте как локально необходимые.

### Что должно появиться кроме метрик

Набор канонических сценариев:

* 51 / неверный тип закрытия
* 60 / хвосты поставщиков
* 97 / lifecycle anomaly
* ОС / карточка vs начисления
* НДС / cross-domain contradiction
* period close impact
* multi-intent
* translit
* follow-up investigation

### От чего отказываемся

От оценки ассистента только по:

* tests passed,
* routed successfully,
* grounding green,
* coverage 1/1.

Этого недостаточно.

### Что это даст

После Этапа 1 вы впервые сможете мерить не “система работает?”, а “она стала полезнее бухгалтеру или нет”.

---

# 5. Полная цепь изменений по контуру

Теперь соберу это не по сущностям, а по **полной цепи выполнения**.

---

## 5.1. Вход сообщения

### Сейчас

Сообщение идёт в normalizer, потом в deterministic routing summary.

### Что меняем

Перед normalizer добавляется тонкий pre-normalization parser:

* alias normalization
* translit normalization
* бытовые бухгалтерские alias
* явная фиксация потенциальных multi-requirement markers

### Цель

Не дать системе потерять смысл до decomposition.

---

## 5.2. Декомпозиция

### Сейчас

Есть requirements extraction, coverage report, dropped-intent tracking, но fine-grained multi-requirement structure всё ещё может compress’иться. 

### Что меняем

* вводим decomposition quality flag;
* вводим обязательную маркировку `intent_loss_risk`;
* soft assumptions становятся видимыми не только в debug, но и влияют на итоговую reply policy;
* broad multi-intent prompts при недостаточном качестве больше не идут в “тихо routed factual answer”.

### Цель

Не скрывать слабую декомпозицию за уверенным downstream answer.

---

## 5.3. Session model

### Сейчас

Есть conversation continuity in-memory, но нет investigation memory.

### Что меняем

В backend session store добавляется `investigation_state`.

### Цель

Связать текущий вопрос с текущим предметом анализа, а не только с текстом чата.

---

## 5.4. Retrieval planning

### Сейчас

Semantic retrieval profile есть; generic prompts всё ещё рыхлые.

### Что меняем

В profile builder добавляем:

* broad query guard
* minimum evidence requirements
* explanation focus
* scope confidence
* degraded answer policy hints

### Цель

Чтобы retrieval перестал быть technically narrowed, но semantically broad.

---

## 5.5. Retrieval execution

### Сейчас

`executeHybrid` уже использует semantic profile и narrowing; это существенный прогресс. Но generic bank/cross-entity queries всё ещё могут давать слишком широкий набор.

### Что меняем

* вводим domain-specific minimum intersections для generic prompts;
* добавляем anti-generic ranking guards;
* усиливаем lifecycle/account/document extraction из snapshot;
* поднимаем mechanism-aware evidence.

### Цель

Не просто narrowed retrieval, а retrieval, который уже несёт механизм проблемы.

---

## 5.6. Result normalization

### Сейчас

Есть normalized retrieval payload, grounding/coverage diagnostics. 

### Что меняем

Расширяем normalized payload так, чтобы composer получал:

* mechanism fields
* defect class
* expected/actual step delta
* period impact hint
* snapshot limitation flag

### Цель

Убрать разрыв между retrieval и answer synthesis.

---

## 5.7. Answer synthesis

### Сейчас

Composer базовый, sufficient for MVP loop, но не policy-grade layer. 

### Что меняем

Новый answer policy:

* route/profile diagnostics уходят на второй план;
* основной narrative anchor = mechanism_of_failure;
* if mechanism weak -> response confidence down;
* if answer broad -> explicit limitation instead of strong conclusion;
* if investigation_state active -> answer binds itself to current focus.

### Цель

Сделать ответ не более красивым, а более предметным.

---

## 5.8. Eval and observability

### Сейчас

Есть tests/build/session/debug traces, но нет полного accountant eval harness.

### Что меняем

* вводим value-oriented metrics;
* фиксируем canonical scenario suite;
* отдельно логируем generic explanation rate, broad answer rate, mechanism specificity.

### Цель

Сделать качество управляемым, а не субъективным.

---

# 6. Что должно быть переписано, а что только усилено

Это важный раздел, потому что ты просил не общие слова, а прям понять: **что переделываем, а что сохраняем**.

## Полностью переписывать на этапе 1 не надо:

* normalizer целиком;
* routing engine;
* assistant endpoint;
* frontend orchestration;
* debug plane;
* existing assistant loop.

## Существенно переделываем:

* session data contract
* retrieval profile builder policy
* retrieval evidence schema
* answer assembly policy
* eval harness

## Частично усиливаем:

* translit/noisy parser
* domain-specific narrowing rules
* decomposition loss detection
* ranking guards
* snapshot signal extraction

## Осознанно оставляем на следующий этап:

* ontology graph
* lifecycle engine formal
* problem-cluster retrieval as default
* iterative orchestrator
* live verification bridge

---

# 7. Архитектурные артефакты, которые должны появиться по итогам этапа

К концу этапа должны появиться не только кодовые изменения, но и новые артефакты.

## Обязательные артефакты

1. `investigation_state` schema
2. `semantic_retrieval_profile` vNext contract
3. `mechanism_aware_evidence_pack` schema
4. `answer_policy_v1_1` spec
5. `decomposition_guardrail` spec
6. `accountant_eval_harness` spec
7. canonical benchmark list
8. regression scenarios for broad query narrowing

---

# 8. Критерии приёмки этапа

Этап считается выполненным не когда “код написан”, а когда выполнены следующие условия.

## 8.1. По состоянию анализа

* сессия хранит `investigation_state`;
* follow-up использует не только chat history, но и active focus / hypotheses / entities;
* система умеет явно продолжать предмет анализа в рамках одной темы.

## 8.2. По retrieval

* generic cross-entity prompts больше не дают “почти полный” narrowed set без понижения confidence и ограничения depth;
* для проблемных route-классов работает broad-query guard;
* retrieval result содержит mechanism-aware evidence fields.

## 8.3. По ответу

* доля generic explanation заметно снижается;
* в ответе появляется конкретная механика дефекта там, где retrieval это реально подтвердил;
* ответ больше не строится вокруг labels, если есть mechanism fields;
* broad answer не выдаётся как strong factual conclusion.

## 8.4. По eval

* введены accountant-facing метрики;
* есть канонический benchmark suite;
* есть baseline before/after comparison.

## 8.5. По архитектурной чистоте

* stage 1 не вносит временных решений, противоречащих последующему ontology/lifecycle/problem-cluster переходу.

---

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

Это тоже надо жёстко зафиксировать.

Этап **не считается выполненным**, если произошло что-то из этого:

* просто улучшили wording ответов;
* просто добавили ещё labels в explanation;
* просто сделали narrowing чуть жёстче без broad-query policy;
* просто расширили session history;
* просто усилили промпт;
* просто добавили новые тесты без accountant eval metrics.

Потому что всё это даёт perceived progress, но не закрывает архитектурную задачу.

---

# 10. Практический идеальный результат этапа

Вот как надо понимать идеальный результат Этапа 1.

После него система **ещё не будет идеальным бухгалтерским ассистентом**.
Но она уже должна перестать быть:

* случайно умной,
* избыточно широкой,
* слишком label-driven,
* слишком route-centric,
* слишком chat-memory-based.

И должна стать:

* устойчивой в broad/focused режимах,
* способной удерживать предмет анализа,
* честной в ограничениях,
* механизмо-ориентированной в evidence,
* измеримой по бухгалтерской полезности.

---

# 11. Короткое управленческое резюме этапа

Если совсем сжато:

**Этап 1 — это не попытка построить бухгалтерский copilot.
Это этап приведения текущего explainable routed assistant к такому состоянию, в котором он перестаёт разваливаться на broad queries, перестаёт терять предмет расследования, начинает собирать mechanism-aware evidence и начинает измеряться по полезности для бухгалтера.
Именно после этого становится рационально переходить к следующему архитектурному слою: problem-cluster retrieval, lifecycle formalization и ontology graph.**

---

Следующим сообщением я могу сделать из этого уже **формальный документ ТЗ в жёсткой структуре** — с разделами “цель / границы / изменения по модулям / контракты / acceptance criteria / out of scope”, чтобы это можно было почти без переработки отдавать в работу.
