CODEX_MASTER_BRIEF.md

# CODEX_MASTER_BRIEF

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

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

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

---

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

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

---

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

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

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

При этом текущая система ещё не является полноценным investigation copilot.  
Основные текущие ограничения:

- snapshot-only truth contour;
- слабая формализация investigation state;
- entity-heavy retrieval;
- недостаточная структурность evidence;
- неполный accountant-facing eval;
- ограниченная управляемость broad / generic query handling;
- отсутствие полноценного bounded investigation runtime;
- отсутствие formal live verification trust model.

Проект развивается по поэтапной схеме.  
На текущей итерации реализуется только **Stage 1 / Foundation Hardening**.  
Этапы 2–6 задают forward-compatibility constraints, но не являются scope текущей реализации.

---

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

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

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

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

---

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

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

### 1. Текущий рабочий scope
- `03_execution/STAGE_01_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/stage-01-foundation-hardening.md`

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

### 4. Текущий статус и общая логика развития
- `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 1 выполняется именно сейчас;
- как Stage 1 стыкуется с дальнейшими этапами.

### 5. Этапы 2–6
- `02_stages/stage-02-...`
- `02_stages/stage-03-...`
- `02_stages/stage-04-...`
- `02_stages/stage-05-...`
- `02_stages/stage-06-...`

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

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

---

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

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

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

- усиление foundation layer без переписывания всей системы;
- минимально необходимая формализация `investigation_state`;
- усиление answer policy;
- усиление broad-query / generic-query handling;
- более структурное представление evidence;
- accountant-facing metrics;
- baseline benchmark/eval harness;
- подготовка базы для следующих этапов без преждевременной реализации этих этапов.

---

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

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

- полноценный problem unit architecture из Stage 2;
- полноценный lifecycle engine из Stage 3;
- полноразмерный ontology / graph runtime из Stage 4;
- investigation engine в полном виде из Stage 5;
- live verification runtime core и full product mode split из Stage 6;
- переезд на новую полную сервисную архитектуру;
- переписывание ассистента вокруг новых abstraction layers без крайней необходимости;
- большие инфраструктурные переделки ради “красоты”.

---

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

**Не строить целевую систему раньше времени.**  
Нужно не “сразу сделать правильно всё”, а “сделать Stage 1 так, чтобы он был структурно корректен, совместим с будущими этапами и не создал новые архитектурные долги”.

---

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

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

### 2. Нельзя подменять архитектурные изменения промптами
Проблемы state, evidence structure, eval, traceability, narrowing и boundedness не должны решаться только промптами или “умной формулировкой ответа”.

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

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

### 5. Все новые сущности должны быть future-compatible
Любые новые:
- типы,
- storage contracts,
- runtime state contracts,
- evidence models,
- metric payloads,
- trace structures

должны проектироваться так, чтобы не конфликтовать со следующими этапами.

### 6. Нельзя маскировать structural gaps perceived-quality улучшениями
Недопустимо заменять структурное решение:
- более длинным ответом,
- более “умным” summarization,
- более агрессивной промптовой маршрутизацией,
- косметическим улучшением вывода.

---

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

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

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

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

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

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

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

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

---

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

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

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

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

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

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

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

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

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

---

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

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

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

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

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

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

---

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

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

### 2. Явные contracts
Всё, что касается:
- state,
- evidence,
- traceability,
- metrics,
- runtime decisions

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

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

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

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

---

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

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

- попытка “сразу построить конечную архитектуру”;
- внедрение лишних сервисов без необходимости;
- скрытая реализация future-stage логики под видом Stage 1;
- замена structural fixes косметикой;
- создание новых абстракций без runtime-пользы;
- переписывание рабочего контура ради абстрактной чистоты;
- смешивание temporary workaround и target architecture без явной маркировки;
- неявное изменение scope;
- неконтролируемая генерация “умных” helper layers;
- перенос ответственности за структурный пробел в prompt layer.

---

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

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

- предлагается большой platform refactor для реализации Stage 1;
- предлагается новая архитектура вместо усиления текущей;
- в код начинают подтягиваться сущности из Stages 4–6 как обязательные;
- вводятся новые сервисы, не дающие прямой пользы на текущем шаге;
- “для удобства” переписывается base loop;
- проблема объясняется как решаемая чисто промптом;
- предлагается сложный orchestrator без прямой необходимости;
- формируется новый data model слой без связи с acceptance criteria Stage 1.

---

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

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

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

---

## Практическая цель первой итерации

Первая итерация должна дать не “идеальную новую систему”, а следующий результат:

- структурно усиленный assistant mode;
- минимальную, но реальную формализацию foundation gaps;
- снижение зависимости от неявной логики и ad hoc поведения;
- более стабильную базу для перехода к следующим этапам.

---

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

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

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

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

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

**Это действительно необходимо для Stage 1, или это попытка преждевременно реализовать следующий этап?**

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