# STAGE_03_TASK_CARD

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

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

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

---

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

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

---

## Контекст

Текущий бухгалтерский ассистент уже работает на уровне функционального MVP+ и после Stage 2 умеет поднимать problem-centric units.  
При этом система ещё не умеет стабильно объяснять проблему как нарушение ожидаемого жизненного цикла объекта.

На текущем этапе нужно **не перестроить ассистента целиком**, а **ввести рабочий lifecycle knowledge layer**, чтобы:

- формально описать состояния и переходы по целевым доменам;
- вычислять current/expected state на runtime-данных;
- классифицировать lifecycle-дефекты;
- обогащать problem units lifecycle-смыслом;
- улучшить ranking и ответы по логике стадии/перехода;
- не тащить prematurely графовое ядро и full investigation engine.

---

## Цель Stage 3

Stage 3 должен дать **lifecycle-aware reasoning слой**, не ломая текущий рабочий контур.

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

- formal lifecycle models для целевых доменов;
- `LifecycleRegistry` как единый source of truth по lifecycle;
- `LifecycleResolver` и `LifecycleDefectClassifier` в runtime;
- `LifecycleEnricher` для problem units;
- lifecycle-aware ranking factors;
- lifecycle-aware answer policy;
- benchmark/eval контур с before/after evidence по ключевым сценариям.

---

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

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

### В scope входят

1. **Формализация lifecycle-доменов**
   - фиксация domain registry;
   - описание lifecycle objects нужного масштаба;
   - описание states/transitions/defects с business-смыслом;
   - обязательный evidence mapping для каждого элемента.

2. **Runtime-слой lifecycle-разрешения**
   - компонент `LifecycleRegistry`;
   - компонент `LifecycleResolver`;
   - компонент `LifecycleDefectClassifier`;
   - компонент `LifecycleEnricher`.

3. **Интеграция lifecycle в problem units**
   - расширение `problem_unit_schema` lifecycle-полями;
   - обогащение unit на runtime-пути;
   - поддержка confidence и snapshot limitations.

4. **Интеграция lifecycle в ranking**
   - добавление lifecycle-based факторов;
   - усиление веса stale/period-impact/cross-branch дефектов по релевантным вопросам;
   - снижение зависимости ranking только от суммы/объёма.

5. **Интеграция lifecycle в answer layer**
   - переход на объяснение через current state, expected state и transition logic;
   - явная связь вывода с evidence;
   - пользовательский next step по месту lifecycle-разрыва.

6. **Quality контур Stage 3**
   - lifecycle resolution tests;
   - defect classification tests;
   - lifecycle-aware explanation tests;
   - benchmark suite по covered domains;
   - before/after eval report.

---

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

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

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

- полный ontology graph runtime из Stage 4;
- полный rule engine по всем типам учёта;
- full investigation orchestrator из Stage 5;
- live verification core runtime из Stage 6;
- full product mode split `direct / investigation / audit`;
- универсальную state machine для всей 1С;
- большой platform refactor ради будущего масштаба;
- замену structural lifecycle-решений косметическими prompt-улучшениями.

---

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

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

### 1. Рабочие lifecycle-модели по целевым доменам
Должны существовать formal-модели как минимум по доменам Stage 3:

- `bank_settlement`;
- `customer_settlement`;
- `deferred_expense`;
- `fixed_asset`;
- `vat_flow`;
- `period_close`.

### 2. Рабочий lifecycle runtime
Должен существовать runtime-контур, который:

- определяет `current_lifecycle_state`;
- определяет `expected_lifecycle_state`;
- находит `missing_transition` и `invalid_transition`;
- классифицирует lifecycle-дефект;
- отдаёт `lifecycle_confidence` и `snapshot_limitations`.

### 3. Lifecycle-enriched problem units
Problem units должны стать lifecycle-aware и включать:

- lifecycle domain;
- lifecycle object;
- stage/transition интерпретацию;
- defect-type;
- business lifecycle interpretation.

### 4. Lifecycle-aware ranking
Ranking должен учитывать lifecycle severity и не сводиться к entities/sum/count.

### 5. Lifecycle-aware ответы
Ответы должны объяснять проблему через логику стадии и перехода, а не через generic labels.

### 6. Измеримость ценности
Должны быть тесты, benchmark и before/after отчёт, подтверждающие улучшение на ключевых сценариях.

---

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

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

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

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

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

3. **Новые или обновлённые contracts / types / schemas**
   - для lifecycle models;
   - для lifecycle resolution;
   - для enriched problem units;
   - для ranking и answer policy;
   - для eval/metrics.

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

5. **Test / eval changes**
   - unit / integration / regression checks;
   - benchmark updates;
   - before/after проверка ценности.

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

---

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

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

### 1. LifecycleDomain
Примерный состав:
- `domain_code`
- `domain_label`
- `supported_object_types`
- `required_evidence_signals`

### 2. LifecycleObject
Примерный состав:
- `lifecycle_object_id`
- `lifecycle_object_type`
- `lifecycle_domain`
- `source_entities`
- `period_context`
- `account_context`
- `document_context`

### 3. LifecycleState
Примерный состав:
- `state_code`
- `state_label`
- `state_class`
- `entry_conditions`
- `exit_conditions`
- `is_terminal`
- `is_problematic`
- `business_meaning`

### 4. LifecycleTransition
Примерный состав:
- `from_state`
- `to_state`
- `transition_type`
- `required_evidence`
- `optional_evidence`
- `forbidden_conditions`
- `business_meaning`

### 5. LifecycleDefect
Примерный состав:
- `defect_code`
- `defect_class`
- `severity_hint`
- `business_meaning`
- `evidence_requirements`
- `period_impact_potential`

### 6. LifecycleResolution
Примерный состав:
- `lifecycle_object_id`
- `resolved_current_state`
- `resolved_expected_state`
- `resolved_previous_states`
- `missing_transitions`
- `invalid_transitions`
- `detected_defects`
- `state_confidence`
- `resolution_evidence`
- `snapshot_limitations`

### 7. LifecycleEnrichedProblemUnit
Примерный состав:
- `problem_unit_id`
- `problem_unit_type`
- `lifecycle_domain`
- `current_lifecycle_state`
- `expected_lifecycle_state`
- `lifecycle_defect_type`
- `missing_transition`
- `invalid_transition`
- `stale_duration`
- `lifecycle_confidence`
- `business_lifecycle_interpretation`

---

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

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

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

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

### 3. Не моделировать абстрактные состояния
Каждое состояние, переход и дефект должны быть распознаваемы по доступным данным.

### 4. Не отделять lifecycle от runtime
Lifecycle считается внедрённым только если используется в resolver, ranking и answer layer.

### 5. Не подменять lifecycle ценность красивым текстом
Смысл Stage 3 — в структурном reasoning, а не в более длинной формулировке ответа.

---

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

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

### Шаг 2. Сделать code-level mapping
Нужно определить:
- где находится текущий lifecycle/signal extraction слой;
- где собирается problem unit;
- где формируется ranking;
- где формируется финальный answer;
- где безопасно подключать lifecycle runtime;
- где подключать benchmark/eval.

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

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

#### Волна 1
- спецификация lifecycle domains/states/transitions/defects;
- контракт registry.

#### Волна 2
- внедрение `LifecycleRegistry` и `LifecycleResolver`.

#### Волна 3
- внедрение `LifecycleDefectClassifier` и `LifecycleEnricher`.

#### Волна 4
- интеграция lifecycle в `problem_unit_schema` и ranking.

#### Волна 5
- интеграция lifecycle в answer layer.

#### Волна 6
- benchmark, before/after eval, acceptance mapping.

---

## Acceptance criteria

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

### A. По моделям
- для каждого целевого домена есть formal lifecycle model;
- states/transitions/defects описаны и привязаны к данным;
- lifecycle-модели не висят отдельно от runtime.

### B. По runtime
- реализован lifecycle resolver;
- problem units реально обогащаются lifecycle-полями;
- defects вычисляются автоматически по retrieval data.

### C. По ranking
- lifecycle severity влияет на ranking;
- stale и period-impact defects поднимаются выше при релевантных вопросах;
- ranking больше не сводится к объёму и сумме.

### D. По ответу
- ответы по covered domains объясняют проблему через state/transition logic;
- generic lifecycle labels уходят на второй план;
- пользователю понятно, какая стадия нарушена.

### E. По ценности
- на сценариях 51/60, 97, ОС, НДС и period close ответы становятся глубже;
- система различает `stalled`, `misclosed`, `not yet completed`, `contradicted`.

### F. По защите от формализма
- для каждого lifecycle domain есть working examples;
- есть benchmark cases;
- есть связка `spec -> runtime -> retrieval -> answer`.

---

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

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

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

---

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

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

- lifecycle описан только на уровне документации;
- resolver не влияет на problem unit, ranking и answer;
- ответы остаются на generic labels;
- состояние нельзя определить по реальным данным;
- предлагается ранний graph-first runtime;
- предлагается full investigation engine;
- ради Stage 3 предлагается большой рефактор transport/routing.

---

## Definition of Done

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

- lifecycle formalization реализована как рабочий runtime-слой;
- problem units стали lifecycle-aware;
- ranking учитывает lifecycle-дефекты по смыслу вопроса;
- ответы строятся на state/transition логике;
- есть benchmark и before/after подтверждение ценности;
- текущий рабочий контур не разрушен;
- нет premature implementation из Stage 4–6.

---

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

**Stage 3 = переход от problem-centric retrieval к lifecycle-aware accounting reasoning.**

Нужно получить не просто новые labels, а рабочую способность системы объяснять:

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