# CODEX_MASTER_BRIEF

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

Этот документ задаёт режим работы Codex по проекту бухгалтерского ассистента.  
Документ не заменяет технические задания по этапам и не заменяет platform core ТЗ.  
Его задача — зафиксировать:

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

---

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

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

---

## Контекст проекта

Разрабатывается бухгалтерский ассистент, который находится в рабочем состоянии на уровне функционального MVP+ и способен:

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

При этом текущая система ещё не является полноценным accountant-grade investigation copilot.  
На текущем переходе считаем этапы 1 и 2 выполненными и переходим к **Stage 3 / Lifecycle Formalization**.

Основные текущие ограничения, которые Stage 3 должен закрыть:

- lifecycle-семантика остаётся частично эвристической;
- отсутствует формализованная модель допустимых состояний/переходов по ключевым доменам;
- problem units недостаточно насыщены temporal и stage-based смыслом;
- ranking по ряду классов вопросов всё ещё тяготеет к frequency/sum/entity сигналам;
- ответы местами остаются на уровне generic lifecycle labels.

---

## Цель работы Codex на текущей итерации

Codex должен помочь реализовать **только Stage 3**, не разрушая текущий рабочий контур и не подтягивая prematurely решения из следующих этапов.

Текущая цель:

- ввести формальную lifecycle-модель по целевым доменам Stage 3;
- внедрить lifecycle runtime-компоненты и их использование в рабочем пути;
- интегрировать lifecycle в problem units, ranking и answer synthesis;
- подтвердить полезность через domain-eval и before/after проверку;
- не превращать текущий этап в скрытую реализацию Stage 4–6.

---

## Иерархия документов

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

### 1. Текущий рабочий scope
- `03_execution/STAGE_03_TASK_CARD.md`

Это главный документ по тому, что делать прямо сейчас.

### 2. Архитектурные ограничения и platform core
- `01_platform/TZ_Platform_Core_Accounting_Assistant_Mode.md`

Этот документ задаёт целевую платформенную рамку:
- storage;
- orchestration;
- trust/provenance;
- observability;
- migration discipline;
- security;
- live bridge policy.

### 3. Детальное ТЗ третьего этапа
- `02_stages/TZ_Stage_3_Lifecycle_Formalization_Assistant_Mode.md`

Этот документ определяет содержимое Stage 3.

### 4. Зависимости Stage 3
- `02_stages/TZ_Stage_2_Retrieval_Unit_Shift_Assistant_Mode.md`

Stage 3 опирается на problem-centric слой Stage 2 и не должен его ломать.

### 5. Текущий статус и общая логика развития
- `00_context/Assistant_Mode_GLOBAL_STATUS_2026-03-24.md`
- `00_context/Assistant_Mode_GLOBAL_STATUS_Appendix_2026-03-24.md`
- `00_context/ROADMAP_endToReal.md`
- `00_context/accounting_assistant_architecture_roadmap.xlsx`

Эти документы нужны для понимания:
- что уже сделано;
- где реальные потолки системы;
- почему сейчас выполняется Stage 3;
- как Stage 3 стыкуется с дальнейшими этапами.

### 6. Этапы 4–6
- `02_stages/TZ_Stage_4_...`
- `02_stages/TZ_Stage_5_...`
- `02_stages/TZ_Stage_6_...`

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

Эти документы **не являются** scope текущей реализации.

---

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

Разрешено делать только то, что относится к Stage 3 и необходимо для его корректной реализации.

К текущему scope относятся:

- формализация lifecycle-доменов и lifecycle-сущностей Stage 3;
- описание states/transitions/defects с привязкой к доступным evidence;
- реализация runtime-слоя (`LifecycleRegistry`, `LifecycleResolver`, `LifecycleDefectClassifier`, `LifecycleEnricher`);
- обновление `problem_unit_schema` lifecycle-полями;
- интеграция lifecycle-факторов в ranking policy;
- интеграция lifecycle-логики в answer policy;
- lifecycle-aware тесты и benchmark контур по ключевым доменам;
- before/after eval отчёт по продуктовой ценности Stage 3.

---

## Что сейчас не является scope

На этой итерации нельзя фактически реализовывать как core-runtime следующие слои:

- полноразмерный ontology / graph runtime из Stage 4;
- полноценный investigation orchestrator из Stage 5;
- live verification runtime core и full product mode split из Stage 6;
- переезд на новую полную сервисную архитектуру;
- переписывание ассистента вокруг новых abstraction layers без крайней необходимости;
- домены, которые не поддерживаются текущими данными/evidence mapping;
- большие инфраструктурные переделки ради “красоты”.

---

## Главный принцип текущей работы

**Не строить целевую систему раньше времени.**  
Нужно сделать Stage 3 так, чтобы lifecycle-модели были не формальными таблицами, а реально работающим runtime-слоем и базой для следующих этапов.

---

## Жёсткие архитектурные ограничения

### 1. Нельзя ломать текущий рабочий контур без прямой причины
Если существующий transport / endpoint / base routing / normalizer pipeline работает, он должен сохраняться, если только изменение не является обязательным условием Stage 3.

### 2. Нельзя подменять архитектурные изменения промптами
Проблемы lifecycle-state, transition logic, defect classification, ranking integration и answer grounding не должны решаться только промптами или “умной формулировкой ответа”.

### 3. Нельзя преждевременно тащить Stage 4–6 в кодовую базу
Если какое-либо изменение фактически реализует future-stage runtime, оно должно быть отклонено или отложено, если не доказана его необходимость для Stage 3.

### 4. Нельзя делать большие рефакторы ради абстрактной чистоты
Разрешены только те изменения, которые:
- закрывают конкретный gap;
- повышают устойчивость текущего слоя;
- не разрушают траекторию дальнейшего развития.

### 5. Каждый lifecycle-элемент обязан иметь полный контур реализации
Для каждого lifecycle-элемента должны существовать:
- spec-level описание;
- runtime-level вычисление;
- retrieval/ranking-level использование;
- answer-level интерпретация.

### 6. Нельзя вводить состояния и дефекты без evidence mapping
Если состояние/переход/дефект нельзя определить по реально доступным данным, его нельзя вводить как runtime-элемент Stage 3.

---

## Порядок работы Codex

Работа должна идти строго по шагам.

### Шаг A. Изучение материалов
Сначала изучить:
- текущий статус;
- platform core ТЗ;
- Stage 3;
- зависимость от Stage 2;
- roadmap;
- контекст следующих этапов.

### Шаг B. Анализ текущего кода
До внесения изменений определить:
- какие части lifecycle already/partially реализованы;
- где находятся реальные точки расширения;
- какие элементы являются хрупкими;
- какие изменения потребуют новых contracts;
- какие части лучше не трогать.

### Шаг C. Подготовка implementation plan
До написания кода выдать план:
- что меняется;
- зачем меняется;
- какие файлы будут затронуты;
- какие новые сущности появятся;
- какие тесты будут добавлены;
- что не будет делаться сейчас.

### Шаг D. Согласованная поэтапная реализация
Только после плана переходить к реализации.

Изменения должны вноситься малыми порциями, чтобы можно было проверить:
- не вышел ли scope за Stage 3;
- не сломан ли текущий контур;
- не появились ли premature abstractions.

### Шаг E. Проверка и фиксация результата
После каждой завершённой волны изменений предоставить:
- summary изменений;
- список изменённых файлов;
- тестовый результат;
- список ограничений;
- список нерешённых вопросов;
- оценку совместимости с дальнейшими этапами.

---

## Первый результат, который Codex должен вернуть до любого кода

До любых patch / refactor / implementation действий Codex должен вернуть документированный анализ следующего вида:

### 1. Summary текущего состояния
Краткое описание того, как текущая реализация устроена по коду.

### 2. Gap analysis относительно Stage 3
Перечень того, чего не хватает для соответствия Stage 3.

### 3. Предлагаемый file-level plan
Какие файлы нужно менять, создавать или расширять.

### 4. Предлагаемые contracts / types / schemas
Какие lifecycle-сущности и интерфейсы появятся.

### 5. Test plan
Какие тесты будут добавлены или обновлены.

### 6. Acceptance mapping
Какие критерии Stage 3 покрываются какими изменениями.

### 7. Explicit non-scope
Что сознательно не будет делаться сейчас.

---

## Требования к формату всех ответов Codex

Каждый содержательный ответ Codex должен быть структурирован.

Обязательная структура:

1. Что было проанализировано  
2. Что обнаружено  
3. Что предлагается изменить  
4. Почему это соответствует Stage 3  
5. Что не входит в текущий scope  
6. Какие файлы затрагиваются  
7. Какие риски есть  
8. Какие тесты или проверки нужны  

Если предлагается кодовое изменение, дополнительно обязательно указывать:

- это локальное изменение или системное;
- ломает ли оно обратную совместимость;
- требует ли миграции;
- влияет ли на transport / routing / problem assembly / ranking / answer composition;
- как это соотносится с будущими этапами.

---

## Правила реализации

### 1. Минимальность изменения
Предпочтительны минимальные архитектурно корректные изменения вместо больших переписываний.

### 2. Явные contracts
Всё, что касается:
- lifecycle states/transitions/defects;
- lifecycle resolution;
- enrichment contracts;
- ranking factors;
- answer interpretation;
- quality metrics

должно оформляться через явные контракты, а не “как получится по месту”.

### 3. Контролируемая расширяемость
Расширяемость допустима, но только в той мере, в которой она:
- реально нужна Stage 3;
- не заставляет внедрять всю будущую архитектуру заранее.

### 4. Наблюдаемость изменений
Если добавляется новая lifecycle-логика, нужно продумать:
- как она тестируется;
- как она логируется;
- как проверяется её корректность;
- как она диагностируется в случае сбоя.

### 5. Миграционная дисциплина
Если изменение создаёт новый контракт или структуру хранения, нужно явно указать:
- где источник истины;
- как происходит инициализация;
- как будет обеспечена совместимость;
- требуется ли миграция данных.

---

## Запрещённые анти-паттерны

Следующие действия считаются ошибочными:

- “красивые lifecycle-таблицы” без рабочего resolver;
- lifecycle-поля в логах без влияния на ranking/answer;
- ответы вида “broken_lifecycle” без state/transition логики;
- скрытая реализация Stage 4–6 под видом Stage 3;
- создание новых абстракций без runtime-пользы;
- переписывание рабочего контура ради абстрактной чистоты;
- неявное изменение scope;
- перенос ответственности за структурный пробел в prompt layer.

---

## Признаки того, что решение идёт не туда

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

- предлагается graph runtime как обязательный путь Stage 3;
- предлагается full investigation orchestration для “удобства”;
- lifecycle-модели проектируются без data/evidence mapping;
- ranking и answer не получают lifecycle-интеграцию;
- для Stage 3 предлагается большой platform refactor;
- формируется новый data model слой без связи с acceptance criteria Stage 3.

---

## Definition of Done для текущей волны

Текущая волна считается завершённой только если выполнены одновременно все условия:

1. Реализован scope Stage 3, а не произвольный “улучшенный вариант”.
2. Текущий рабочий контур не разрушен.
3. Новые lifecycle contracts описаны явно.
4. Есть тесты и/или проверяемые критерии для внесённых изменений.
5. Нет скрытого уезда в Stage 4–6.
6. Изменения совместимы с platform core ТЗ.
7. Зафиксировано, что сознательно осталось за пределами текущего этапа.

---

## Практическая цель текущей итерации

Текущая итерация должна дать следующий результат:

- lifecycle-aware problem reasoning вместо generic lifecycle labels;
- stage/transition-aware ranking на covered-доменах;
- более прикладные ответы по сценариям 51/60, 97, ОС, НДС и period close;
- рабочий lifecycle runtime-контур, пригодный для дальнейшего развития.

---

## Финальная установка для Codex

Работать нужно в режиме **supervised implementation**.

Это означает:

- сначала анализ;
- потом план;
- потом небольшие контролируемые изменения;
- после каждого куска — отчёт о том, что сделано и что осталось;
- никакой самовольной замены roadmap;
- никакого расширения scope;
- никакой premature architecture.

Главный вопрос перед любым изменением:

**Это действительно необходимо для Stage 3, или это попытка преждевременно реализовать Stage 4–6?**

Если ответ неочевиден, изменение откладывается и выносится на отдельное согласование.
