STAGE_01_TASK_CARD.md

# STAGE_01_TASK_CARD

## Назначение документа

Этот документ фиксирует **рабочий scope первой итерации реализации** для Codex и разработчика.  
Документ не заменяет Stage 1 ТЗ и не заменяет platform core ТЗ.  
Его задача — перевести первый этап в **практический implementation scope**, который можно брать в работу без расползания в следующие этапы.

Документ должен использоваться как основной рабочий ориентир при реализации первой волны изменений.

---

## Статус документа

- Статус: рабочая карта реализации Stage 1
- Язык: русский
- Режим использования: обязателен к прочтению перед любыми изменениями по Stage 1
- При конфликте по архитектурным ограничениям приоритет имеет `TZ_Platform_Core_Accounting_Assistant_Mode.md`
- При конфликте по общему режиму работы Codex приоритет имеет `CODEX_MASTER_BRIEF.md`

---

## Контекст

Текущий бухгалтерский ассистент уже работает на уровне функционального MVP+:

- принимает вопросы пользователя;
- обращается к доступным данным;
- извлекает информацию;
- формирует объяснение;
- возвращает ответ.

При этом система ещё не является полноценным investigation copilot.  
На текущем этапе нужно **не перестроить ассистента целиком**, а **укрепить foundation layer**, чтобы:

- убрать самые опасные structural gaps;
- сделать поведение более управляемым;
- снизить зависимость от неявной логики;
- подготовить совместимую базу для Stage 2–6;
- не тащить prematurely будущую архитектуру в текущую реализацию.

---

## Цель Stage 1

Stage 1 должен дать **структурно усиленный assistant mode**, не ломая текущий рабочий контур.

Практический результат этапа:

- минимально формализованный `investigation_state`;
- более управляемое поведение на broad / generic questions;
- более структурное и объяснимое представление evidence;
- accountant-facing метрики качества;
- baseline benchmark/eval harness;
- улучшение answer policy без ухода в prompt-only компенсацию;
- база для следующих этапов без преждевременной реализации problem units / lifecycle / graph / investigation engine / live verification.

---

## Scope текущей реализации

В рамках Stage 1 разрешено реализовывать только то, что необходимо для foundation hardening.

### В scope входят

1. **Минимальная формализация investigation state**
   - базовый state-контур для многошагового взаимодействия;
   - фиксация контекста текущего вопроса и follow-up логики;
   - хранение минимально необходимого состояния для продолжающегося разбора;
   - отделение state от случайной chat-памяти.

2. **Усиление broad / generic query handling**
   - обнаружение слишком широких, размытых или недоопределённых запросов;
   - controlled narrowing;
   - управляемый переход от broad-вопроса к более точной постановке;
   - снижение generic explanation без опоры только на “умный текст”.

3. **Более структурное evidence-представление**
   - evidence должно быть не просто текстовым пересказом;
   - нужны явные поля/слоты под происхождение, тип опоры, степень уверенности, механизм/основание;
   - ответ не должен строиться на неявной сборке “по месту”.

4. **Усиление answer policy**
   - ответ должен быть полезным бухгалтеру;
   - должен быть более дисциплинированный формат объяснения;
   - должна снижаться доля общих и малооперабельных ответов;
   - при отсутствии достаточной опоры система должна это явно обозначать.

5. **Accountant-facing metrics**
   - нужны метрики не только технического прохождения пайплайна, но и полезности ответа для бухгалтерского сценария;
   - должна появиться измеримость качества на уровне пользовательского результата.

6. **Baseline benchmark / eval harness**
   - минимальный воспроизводимый контур проверки качества;
   - возможность сравнивать поведение до/после изменений;
   - возможность фиксировать деградации.

7. **Минимальные foundation-изменения в коде**
   - только те изменения, которые необходимы для реализации пунктов выше;
   - без большого переписывания существующей системы.

---

## Что не входит в scope

Следующие вещи **не должны** реализовываться в рамках Stage 1 как core-runtime или как полноценный новый слой.

### Не делать сейчас

- полный `problem unit architecture`;
- полноценный lifecycle engine;
- полноценный ontology / graph runtime;
- full investigation engine;
- live verification runtime core;
- full product mode split (`direct / investigation / audit`);
- новый большой orchestration layer;
- радикальную смену transport / endpoint / base routing;
- большой platform refactor;
- сервисную декомпозицию ради будущего масштаба;
- замену structural fixes косметическими prompt-улучшениями.

---

## Обязательные результаты этапа

По завершении Stage 1 в системе должны появиться следующие результаты.

### 1. Базовый investigation state
Должен существовать минимальный, но явный state-контур, который:

- поддерживает follow-up вопросы;
- позволяет не терять контекст разбора;
- не сводится к “последнему сообщению в чате”;
- не имитирует полноценный investigation engine;
- не противоречит будущему расширению в Stage 5.

### 2. Controlled broad-query narrowing
Система должна уметь:

- распознавать слишком общие вопросы;
- не выдавать сразу слабый обобщённый ответ как будто вопрос уже достаточно определён;
- либо сужать вопрос,
- либо честно сигнализировать о недостатке точности,
- либо предлагать следующий полезный шаг в рамках текущего контура.

### 3. Mechanism-aware evidence baseline
В ответной логике должна появиться хотя бы базовая evidence-структура, включающая:

- источник / происхождение;
- тип evidence;
- основание ответа;
- степень опоры / уверенности;
- связь между утверждением и evidence.

### 4. Accountant-facing answer discipline
Ответы должны стать более пригодными для прикладного использования бухгалтером:

- меньше generic prose;
- больше предметной объяснимости;
- больше локальной операбельности;
- ясное разделение между найденным, предполагаемым и недостающим.

### 5. Метрики и eval
Должен появиться baseline-контур, позволяющий измерять:

- качество narrowing;
- качество evidence-linking;
- долю generic answers;
- долю structurally useful answers;
- стабильность поведения на контрольном наборе вопросов.

---

## Рабочие deliverables от Codex

Codex должен вернуть не только код, но и набор артефактов.

### Обязательные deliverables

1. **Gap analysis по Stage 1**
   - чего не хватает в текущем коде;
   - что уже есть частично;
   - где точки внедрения.

2. **Implementation plan**
   - какие компоненты меняются;
   - какие файлы меняются;
   - какие сущности появляются;
   - что остаётся нетронутым.

3. **Новые или обновлённые contracts / types / schemas**
   - для state;
   - для evidence;
   - для answer policy;
   - для eval/metrics.

4. **Кодовые изменения**
   - малыми контролируемыми порциями;
   - без скрытого выезда в Stage 2–6.

5. **Test / eval changes**
   - unit / integration / regression checks;
   - baseline benchmark updates;
   - проверка, что Stage 1 реально усиливает foundation.

6. **Итоговый отчёт по волне**
   - что сделано;
   - что не сделано сознательно;
   - какие риски остались;
   - что готово для следующего этапа.

---

## Предпочтительные направления изменений в коде

Ниже перечислены типы изменений, которые допустимы и ожидаемы.

### 1. State layer
Можно и нужно:
- добавить минимальные state-типы;
- добавить state storage contract;
- добавить controlled state hydration / update;
- ограничить state только тем, что реально нужно Stage 1.

Нельзя:
- строить full investigation machine;
- вводить сложный branching runtime;
- реализовывать полноценные investigation cases.

### 2. Retrieval / interpretation boundary
Можно и нужно:
- усилить слой, где broad/generic вопрос распознаётся до финального ответа;
- добавить явную логику narrowing;
- отделить “данных недостаточно для узкого ответа” от “модель решила ответить общими словами”.

Нельзя:
- заменять structural logic prompt tuning-only подходом;
- внедрять problem unit runtime раньше Stage 2.

### 3. Evidence layer
Можно и нужно:
- сделать evidence более формализованным;
- добавить типизацию evidence;
- связать утверждение с основанием.

Нельзя:
- строить полный ontology graph;
- вводить тяжёлую графовую модель без реальной необходимости.

### 4. Answer composer / policy
Можно и нужно:
- дисциплинировать формат ответа;
- сделать явные режимы ответа внутри Stage 1;
- снизить долю размытых формулировок.

Нельзя:
- строить full mode router уровня Stage 6;
- подменять quality строгим шаблоном без связи с evidence.

### 5. Eval / metrics
Можно и нужно:
- добавить baseline метрики;
- добавить контрольные наборы вопросов;
- добавить сравнение до/после.

Нельзя:
- ограничиться только техническими green tests;
- считать этап завершённым без accountant-facing проверки.

---

## Ожидаемые сущности Stage 1

Ниже — не финальная схема данных, а минимальный набор сущностей, который допустимо и полезно ввести уже сейчас.

### 1. InvestigationState
Минимальный runtime state текущего разбора.

Примерный состав:
- `session_id`
- `question_id`
- `current_focus`
- `narrowing_status`
- `evidence_refs`
- `open_uncertainties`
- `last_answer_mode`
- `followup_context`

Это не должен быть полноценный case-engine.

### 2. EvidenceItem
Базовая единица evidence.

Примерный состав:
- `evidence_id`
- `source_type`
- `source_ref`
- `claim_ref`
- `evidence_kind`
- `mechanism_note`
- `confidence`
- `raw_excerpt_or_pointer`

### 3. AnswerStructure
Формализованный каркас ответа.

Примерный состав:
- `answer_summary`
- `direct_answer`
- `evidence_block`
- `uncertainty_block`
- `next_step_block`

### 4. EvalRecord
Запись о результате проверки на benchmark / control set.

Примерный состав:
- `case_id`
- `question_type`
- `broadness_level`
- `narrowing_result`
- `evidence_quality_score`
- `genericness_score`
- `accountant_usefulness_score`
- `notes`

---

## Жёсткие implementation-ограничения

### 1. Не трогать без необходимости
Без прямой нужды не переписывать:
- transport layer;
- endpoint layer;
- base routing;
- normalizer pipeline;
- рабочий контур выдачи ответа.

### 2. Не внедрять будущие этапы скрыто
Если предлагаемое изменение:
- требует graph runtime,
- требует lifecycle engine,
- требует full investigation runtime,
- требует live verification core,

то оно не относится к Stage 1 и должно быть отложено.

### 3. Не раздувать abstraction layer
Если новая абстракция:
- не даёт прямой пользы текущему этапу,
- не закрывает конкретный gap,
- добавляется “на будущее”,

она не должна внедряться.

### 4. Не подменять state чатом
State должен быть формализован минимально, но явно.  
Нельзя считать, что “история переписки и так всё хранит”.

### 5. Не подменять evidence текстом
Evidence должно быть хотя бы базово структурировано.  
Нельзя считать, что “если модель сослалась словами, этого достаточно”.

---

## Порядок работы по Stage 1

### Шаг 1. Прочитать материалы
Обязательно прочитать:
- `CODEX_MASTER_BRIEF.md`
- `TZ_Platform_Core_Accounting_Assistant_Mode.md`
- Stage 1 ТЗ
- status documents
- roadmap

### Шаг 2. Сделать code-level mapping
Нужно определить:
- где находится текущий assistant loop;
- где принимается решение по типу вопроса;
- где собирается evidence;
- где формируется финальный ответ;
- где можно безопасно внедрить state;
- где можно подключить eval/metrics.

### Шаг 3. Подготовить plan без кода
До начала реализации Codex должен выдать:
- gap analysis;
- file-level plan;
- список новых контрактов;
- список новых тестов;
- список non-scope.

### Шаг 4. Реализовывать малыми волнами
Рекомендуемая последовательность:

#### Волна 1
- mapping текущего кода;
- проектирование новых contracts;
- проектирование state baseline.

#### Волна 2
- внедрение minimal `investigation_state`;
- базовое сохранение и использование state.

#### Волна 3
- внедрение evidence-структуры;
- обновление answer composer.

#### Волна 4
- усиление broad/generic query handling;
- controlled narrowing.

#### Волна 5
- добавление accountant-facing metrics и baseline eval harness.

#### Волна 6
- regression pass;
- acceptance mapping;
- cleanup только по необходимости.

---

## Acceptance criteria

Stage 1 считается закрытым только если выполнены все критерии ниже.

### A. Investigation state
- существует явный минимальный state-контур;
- он реально участвует в follow-up логике;
- он не конфликтует с будущим расширением;
- он не имитирует Stage 5.

### B. Broad-query behavior
- broad/generic вопросы обрабатываются более дисциплинированно;
- система не скатывается в пустые общие ответы;
- narrowing либо выполняется, либо честно сигнализируется;
- поведение стало более предсказуемым.

### C. Evidence structure
- evidence имеет явную структуру;
- связь между ответом и evidence стала лучше;
- механизм/основание ответа отображается более прозрачно;
- “ответ без опоры” не маскируется уверенностью.

### D. Answer quality
- ответ стал более полезным для бухгалтерского сценария;
- genericness снизилась;
- uncertainty стала видимой и контролируемой;
- улучшение не сводится только к косметике.

### E. Eval / metrics
- существует baseline benchmark/eval harness;
- есть набор контрольных кейсов;
- можно сравнить поведение до/после;
- accountant-facing метрики зафиксированы.

### F. Scope discipline
- нет скрытого выезда в Stages 2–6;
- нет большого platform refactor;
- нет ненужной сервисной декомпозиции;
- нет замены structural fixes промптами.

---

## Что Codex обязан явно указать в конце работы

В финальном отчёте по Stage 1 обязательно должны быть разделы:

1. Что было сделано  
2. Какие файлы изменены  
3. Какие новые сущности введены  
4. Какие тесты добавлены  
5. Какие acceptance criteria закрыты  
6. Что сознательно НЕ реализовано  
7. Какие риски и ограничения остались  
8. Что подготовлено для Stage 2  

---

## Красные флаги

Если в ходе работы появляется одно из следующего, реализацию нужно остановить и пересобрать plan:

- Codex предлагает полный redesign ассистента;
- появляется зависимость от graph layer;
- появляется попытка строить investigation engine;
- broad-query проблема решается только красивым текстом;
- state превращается в неявную chat memory;
- evidence остаётся текстовым пересказом без структуры;
- метрики ограничиваются только техническими тестами;
- ради Stage 1 предлагается большой рефактор transport/routing.

---

## Definition of Done

Stage 1 завершён, если одновременно соблюдены все условия:

- foundation layer реально усилен;
- текущий рабочий контур не разрушен;
- введён минимальный `investigation_state`;
- broad/generic handling стал более управляемым;
- evidence стало более структурным;
- появились accountant-facing метрики;
- есть baseline eval harness;
- изменения совместимы с platform core;
- нет premature implementation из следующих этапов.

---

## Короткая практическая формула этапа

**Stage 1 = не новая архитектура, а жёсткое усиление основания.**

Нужно получить не “почти готовый конечный продукт”, а:

- более дисциплинированный assistant mode;
- более формализованный foundation layer;
- меньше неявности;
- меньше generic-ответов;
- больше контролируемости;
- больше готовности к Stage 2 и дальше.