# STAGE_04_TASK_CARD

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

Этот документ фиксирует **рабочий implementation scope четвёртого этапа** для Codex и разработчика.
Документ не заменяет Stage 4 ТЗ и не заменяет platform core ТЗ.
Его задача — перевести Stage 4 в практический рабочий контур без расползания в Stage 5–6.

---

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

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

---

## Контекст

- Stage 3 закрыт и принят (2026-03-26).
- Текущий baseline: lifecycle-aware reasoning работает, Stage 2 regression и Stage 3 probe разделены.
- Следующий шаг — не расширять prompt-слой, а ввести graph-backed causal layer как основу для дальнейшего investigation режима.

Опорные артефакты закрытия Stage 3:
- `llm_normalizer/docs/runs/2026-03-26_Stage_3_Wave_6_Mojibake_Final_MicroPatch`

Стартовая run-папка Stage 4 Wave 1:
- `llm_normalizer/docs/runs/2026-03-26_Stage_04_Wave_01_Kickoff`

---

## Цель Stage 4

Stage 4 должен дать **рабочее graph-ядро бухгалтерской предметной области**, чтобы retrieval, lifecycle и problem assembly опирались на единое причинно-следственное представление.

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

- типизированные graph-узлы и связи для ключевых бухгалтерских сущностей;
- runtime-построение графа с provenance/confidence;
- graph-aware planning/execution для graph-eligible запросов;
- graph-backed problem assembly и lifecycle binding;
- более причинные и проверяемые пользовательские ответы;
- измеримое улучшение по benchmark/eval.

---

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

### В scope входят

1. **Graph contracts и schema layer**
   - `AccountingGraphNode`;
   - `AccountingGraphEdge`;
   - `GraphSchemaRegistry`;
   - доменные типы узлов/связей для покрываемых сценариев.

2. **Graph runtime core**
   - `GraphBuilder`;
   - `GraphTraversalPolicy`;
   - `GraphProvenanceLayer`;
   - `GraphValidationLayer`.

3. **Интеграция в retrieval path**
   - graph eligibility в planner;
   - typed traversal в execution для graph-eligible кейсов;
   - детекция missing/conflicting links как runtime сигналов.

4. **Интеграция в problem/lifecycle layers**
   - graph-backed problem assembly;
   - graph-backed lifecycle transition checks;
   - корректная передача graph evidence в answer layer.

5. **Интеграция в answer layer**
   - user-facing объяснение по causal path;
   - явная фиксация отсутствующих/конфликтных связей;
   - сохранение честных ограничений confidence/coverage.

6. **Quality контур Stage 4**
   - unit/integration тесты graph core;
   - regression на Stage 2/Stage 3 маршрутах;
   - benchmark/eval до/после по graph value сценариям.

---

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

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

- полноценный Investigation Engine Stage 5;
- full orchestration case-runtime с глубокой ветвизацией;
- live verification core path и full mode split Stage 6;
- глобальный enterprise graph beyond accounting core Stage 4;
- большой рефактор transport/endpoint/base routing;
- попытки закрыть graph-gap только prompt-изменениями.

---

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

### 1. Рабочая graph-модель по целевым доменам

Должны быть внедрены типизированные узлы/связи как минимум для доменов, критичных для текущего набора кейсов:

- 51/60 расчётные цепочки;
- 97 (расходы будущих периодов);
- ОС;
- НДС;
- period_close.

### 2. Рабочий graph runtime

Должен существовать runtime-контур, который:

- строит graph из нормализованных сущностей;
- хранит provenance/confidence;
- поддерживает typed traversal;
- выявляет missing/conflicting edges.

### 3. Graph-backed retrieval и problem assembly

- graph-eligible queries реально используют traversal;
- problem units используют graph connectivity, а не только proximity/heuristics.

### 4. Graph-backed lifecycle binding

- lifecycle transition checks используют graph relations;
- missing/invalid transitions имеют graph-опору.

### 5. Улучшение user-facing объяснений

- ответы показывают причинный путь проблемы;
- видны узлы/связи разрыва;
- сохраняется прозрачность uncertainty.

### 6. Измеримость ценности

- есть benchmark suite;
- есть before/after evidence;
- есть отчёт, где именно graph layer даёт прирост качества.

---

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

Минимальный набор сущностей/компонентов:

1. `AccountingGraphNode`
2. `AccountingGraphEdge`
3. `GraphSchemaRegistry`
4. `GraphBuilder`
5. `GraphTraversalPolicy`
6. `GraphProvenanceLayer`
7. `GraphValidationLayer`
8. `GraphBackedProblemAssembly`
9. `GraphBackedLifecycleBinding`

---

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

### 1. Не ломать рабочий контур

Без прямой необходимости не переписывать:
- transport;
- endpoint;
- base routing;
- normalizer pipeline.

### 2. Graph только с runtime-value

Graph считается внедрённым только если влияет на:
- retrieval execution;
- problem assembly;
- lifecycle reasoning;
- user-facing explanation.

### 3. Никаких бездоказательных узлов/связей

Нельзя добавлять node/edge, если нет:
- источника данных;
- evidence mapping;
- provenance trace.

### 4. Stage 5/6 не реализовывать внутри Stage 4

Любая попытка внедрить full investigation orchestration или live verification core отклоняется как non-scope.

---

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

### Шаг 1. Прочитать материалы

Обязательно прочитать:
- `CODEX_MASTER_BRIEF.md`
- `TZ_Platform_Core_Accounting_Assistant_Mode.md`
- `TZ_Stage_4_Accounting_Ontology_Graph_Core_Assistant_Mode.md`
- `TZ_Stage_3_Lifecycle_Formalization_Assistant_Mode.md`
- `TZ_Stage_2_Retrieval_Unit_Shift_Assistant_Mode.md`

### Шаг 2. Сделать code-level mapping

Нужно определить:
- где безопасно встраивать graph builder;
- где planner/execution могут включать graph traversal;
- где problem/lifecycle layers принимают graph evidence;
- где answer layer получает causal path.

### Шаг 3. План без кода

До начала реализации Codex обязан вернуть:
- gap analysis;
- file-level plan;
- contracts/types plan;
- test/eval plan;
- explicit non-scope.

### Шаг 4. Реализация малыми волнами

Рекомендуемая последовательность:

- Волна 1: graph schema + registry;
- Волна 2: graph builder + provenance;
- Волна 3: retrieval planner/execution graph integration;
- Волна 4: problem/lifecycle graph binding;
- Волна 5: answer integration;
- Волна 6: benchmark/eval + hardening.

---

## Acceptance criteria (кратко)

Stage 4 считается закрытым только если одновременно:

1. Graph contracts реализованы и используются runtime.
2. Graph traversal реально участвует в graph-eligible запросах.
3. Problem assembly использует graph connectivity.
4. Lifecycle checks используют graph transitions.
5. User-facing ответы отражают causal graph path.
6. Есть before/after подтверждение улучшения.
7. Нет скрытого выезда в Stage 5–6.
8. Run-артефакты оформлены по стандарту `date -> Stage -> Wave`, включая `prompt_dialogs`.

---

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

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

---

## Definition of Done

Stage 4 завершён, если одновременно:

- graph-ядро работает в runtime, а не только в документации;
- retrieval/problem/lifecycle/answer слои используют graph signals;
- ответы становятся причинно связными и проверяемыми;
- есть измеримая прибавка по benchmark/eval;
- рабочий контур не разрушен;
- нет premature implementation Stage 5–6.

---

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

**Stage 4 = переход от lifecycle-aware reasoning к graph-backed accounting causality.**
