ARCHITECTURE_GUARDRAILS.md

# ARCHITECTURE_GUARDRAILS

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

Этот документ фиксирует **жёсткие архитектурные рамки** для работы Codex и разработчика по бухгалтерскому ассистенту.

Документ нужен, чтобы:

- не допустить расползания scope;
- не дать текущей реализации преждевременно превратиться в Stage 2–6;
- не допустить появления скрытых костылей под видом “улучшения архитектуры”;
- удержать изменения в рамках текущего этапа;
- сохранить совместимость с будущим развитием системы.

Документ не заменяет:
- `CODEX_MASTER_BRIEF.md`
- `STAGE_01_TASK_CARD.md`
- `TZ_Platform_Core_Accounting_Assistant_Mode.md`
- этапные ТЗ

Его задача — фиксировать **что можно**, **что нельзя** и **по каким признакам видно, что реализация пошла не туда**.

---

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

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

---

## Базовая установка

Текущая задача — **не построить конечную архитектуру**, а **усилить существующую систему так, чтобы она стала устойчивой основой для следующих этапов**.

Следовательно:

- нельзя преждевременно тащить в код будущие слои;
- нельзя переписывать рабочий контур ради абстрактной чистоты;
- нельзя маскировать structural gaps косметикой;
- нельзя заменять архитектуру “умным” поведением промптов.

---

## Главный принцип

**Каждое изменение должно отвечать на вопрос:**

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

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

---

## Архитектурная позиция проекта

Развитие системы должно идти поэтапно.

### Текущая логика развития
1. Усиление foundation
2. Сдвиг retrieval units
3. Формализация lifecycle
4. Формирование graph core
5. Построение investigation engine
6. Live verification и product modes

Из этого следует:

- текущий этап не должен содержать скрытую реализацию graph runtime;
- текущий этап не должен содержать полноценный investigation engine;
- текущий этап не должен содержать полноценный mode router;
- текущий этап не должен содержать live verification core path;
- текущий этап не должен содержать premature orchestration architecture.

---

## Что считается архитектурно допустимым

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

1. закрывают конкретный gap текущего этапа;
2. дают прямую runtime-пользу уже сейчас;
3. не тянут в код полноразмерные future-stage слои;
4. не ломают текущий рабочий контур;
5. не создают новый труднообратимый архитектурный долг.

---

## Что считается архитектурно недопустимым

Недопустимы изменения, которые:

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

---

## Жёсткие guardrails

### 1. Не переписывать рабочий контур без прямой причины

Без крайней необходимости запрещено переписывать:

- transport layer;
- endpoint layer;
- base routing;
- normalizer pipeline;
- текущий путь сборки ответа;
- рабочий retrieval flow;
- уже действующий assistant loop.

Разрешены только точечные изменения, если они:
- прямо обязательны для Stage 1;
- не могут быть внесены более локально.

---

### 2. Не строить новую архитектуру вместо усиления текущей

Нельзя использовать текущий этап как повод для:

- полного redesign системы;
- переезда на другую базовую схему исполнения;
- внедрения большого orchestration layer;
- скрытого перехода на новую core-модель;
- замены существующей структуры на “более правильную” без немедленной пользы.

---

### 3. Не внедрять преждевременно Stage 2–6

До наступления соответствующих этапов запрещено внедрять как core-runtime:

- полноценный `problem unit architecture`;
- полноценный lifecycle engine;
- полноразмерный ontology/graph runtime;
- full investigation engine;
- live verification core;
- split product runtime `direct / investigation / audit`;
- тяжёлую multi-step orchestration system;
- систему ветвления расследований как основной путь выполнения.

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

---

### 4. Не решать structural gaps только промптами

Запрещено считать, что следующие проблемы решены, если было сделано только prompt tuning:

- отсутствие формального state;
- слабое evidence-linking;
- generic response behavior;
- отсутствие boundedness;
- отсутствие quality metrics;
- неявная uncertainty handling;
- отсутствие управляемого narrowing.

Промпт может помогать, но не может быть единственной формой архитектурного решения.

---

### 5. Не подменять state историей чата

Запрещено считать, что:
- chat history,
- предыдущий ответ,
- контекст последнего сообщения

эквивалентны формальному state.

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

---

### 6. Не подменять evidence текстовой убедительностью

Запрещено считать, что ответ “обоснован”, если модель просто написала убедительный текст.

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

---

### 7. Не вводить абстракции “на будущее” без runtime-пользы

Любая новая абстракция должна быть оправдана текущей пользой.

Недопустимы:
- интерфейсы ради гипотетического расширения;
- service layers без прямой функции на текущем этапе;
- сложные фабрики/адаптеры/оркестраторы “на потом”;
- обобщения, которые пока ничего не упрощают.

---

### 8. Не раздувать сервисную архитектуру раньше времени

Запрещено добавлять отдельные сервисы, если задачу можно решить проще.

Не нужно сейчас:
- выделять отдельные сервисы ради формального микросервисного вида;
- дробить систему под будущий scale, которого ещё нет;
- вводить сетевое взаимодействие между модулями, где достаточно модульной декомпозиции в кодовой базе;
- строить платформенный контур сложнее, чем требует текущий этап.

---

### 9. Не вводить storage complexity без ясной причины

Разрешено вводить новые contracts и storage-слои только если понятно:

- что является source of truth;
- что хранится как runtime state;
- что хранится как derived artifacts;
- как обеспечивается совместимость;
- как это будет использоваться уже сейчас.

Недопустимо:
- размазывать состояние по случайным местам;
- хранить критичное состояние в ad hoc формате;
- смешивать runtime state, long-term artifacts и временные вспомогательные данные без явной дисциплины.

---

### 10. Не считать green tests доказательством качества продукта

Если изменения прошли технические тесты, это ещё не означает, что этап закрыт.

Архитектурно недостаточно:
- unit tests без проверки полезности ответа;
- integration tests без accountant-facing criteria;
- успешного пайплайна без оценки качества narrowing/evidence/usefulness.

---

## Разрешённые архитектурные паттерны

Ниже перечислено то, что допустимо и желательно.

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

### 2. Локальное усиление точки принятия решения
Если есть конкретная слабая зона, допустимо:
- локально усилить её;
- формализовать решение;
- добавить проверку/метрику;
- не затрагивать весь контур.

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

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

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

---

## Decision rules перед любым изменением

Перед внесением любого изменения нужно проверить следующее.

### Вопрос 1
Это закрывает конкретный gap текущего этапа?

Если нет — изменение отклоняется.

### Вопрос 2
Это можно сделать локальнее?

Если да — выбирается более локальный вариант.

### Вопрос 3
Это не тянет Stage 2–6 раньше времени?

Если тянет — изменение откладывается или упрощается.

### Вопрос 4
Это даёт прямую runtime-пользу уже сейчас?

Если нет — изменение подозрительно.

### Вопрос 5
Это не создаёт новый трудный долг?

Если создаёт — нужен другой вариант.

### Вопрос 6
Это не решает проблему только косметикой?

Если решает только косметикой — изменение недостаточно.

---

## Проверка на scope drift

Признаки того, что реализация вышла за рамки:

- в код попали сущности, которые фактически образуют graph runtime;
- появилась логика сложного branching investigation;
- появился mode router для нескольких продуктовых режимов;
- появилась зависимость от live verification core;
- ради текущего этапа меняется половина репозитория;
- вводятся сущности, которые пока никто не использует;
- строится общий orchestration framework вместо локального усиления;
- Codex объясняет сложность тем, что “так будет лучше на будущее”.

Если наблюдается один или несколько признаков — нужно остановить изменения и сократить scope.

---

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

Следующие ситуации считаются тревожными:

1. Предлагается переписать base loop  
2. Предлагается “сразу сделать правильно всю архитектуру”  
3. Предлагается отдельный graph layer уже сейчас  
4. Предлагается большой orchestration framework  
5. Предлагается product split runtime уже на первом этапе  
6. State остаётся неявным, но промпт становится длиннее  
7. Evidence описывается красивее, но не структурируется  
8. Метрики остаются только техническими  
9. Добавляются новые сервисы без реальной необходимости  
10. Временное решение подаётся как target architecture  

---

## Правило minimal irreversible change

Любое изменение должно быть по возможности:

- минимальным;
- обратимым;
- наблюдаемым;
- проверяемым;
- совместимым с дальнейшими этапами.

Нельзя делать решение, которое:
- сложно откатить;
- сложно объяснить;
- сложно протестировать;
- сложно встроить в дальнейшую архитектуру;
- принято только потому, что “быстрее сейчас”.

---

## Правило explicit source of truth

Для каждой новой сущности должно быть явно определено:

- где находится источник истины;
- кто её обновляет;
- кто её читает;
- как она версионируется;
- что является derived form, а что canonical form.

Если это не определено, сущность не готова к внедрению.

---

## Правило bounded state

Любой новый state должен быть:

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

Нельзя вводить state, который:
- хранит всё подряд;
- не имеет чётких полей;
- зависит от неявных текстовых интерпретаций;
- фактически дублирует chat history;
- не имеет правил обновления.

---

## Правило honest uncertainty

Система не должна производить архитектурно ложную определённость.

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

Запрещено:
- маскировать отсутствие опоры уверенным тоном;
- расширять answer prose вместо усиления основания;
- выдавать общую формулировку как точный вывод.

---

## Правило compatibility without premature implementation

Система должна быть совместима с будущими этапами, но не должна их реализовывать заранее.

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

Недопустимо:
- включать полный будущий runtime;
- строить будущий слой целиком;
- обосновывать сложность только будущими гипотетическими выгодами.

---

## Как должен выглядеть хороший change proposal

Хорошее предложение по изменению должно содержать:

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

Если хотя бы половина этих пунктов отсутствует, proposal недостаточно дисциплинирован.

---

## Как должен выглядеть плохой change proposal

Плохим считается предложение, если в нём есть формулировки типа:

- “сразу сделаем правильно на будущее”
- “заодно перепишем”
- “проще построить новый слой”
- “пусть пока будет так, потом переделаем”
- “можно промптом компенсировать”
- “сделаем универсальную архитектуру”
- “вдруг потом пригодится”
- “это подготовка к следующим этапам”

Без доказанной текущей пользы такие аргументы не принимаются.

---

## Эскалация при спорном решении

Если изменение спорное, применять следующий порядок:

1. Проверить соответствие текущему scope  
2. Проверить соответствие platform core ТЗ  
3. Проверить, не тянет ли изменение Stage 2–6  
4. Проверить, можно ли сделать локальнее  
5. Зафиксировать риски  
6. Только после этого принимать решение  

Если спор остаётся, решение не внедряется автоматически.

---

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

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

### Что не делать
- строить будущее раньше времени;
- переписывать рабочее;
- лечить архитектуру текстом;
- плодить абстракции;
- усложнять платформу без необходимости.

---

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

Архитектурная дисциплина в этом проекте важнее скорости декоративных изменений.

Главная цель текущего этапа:

**не сделать видимость зрелой системы, а реально уменьшить structural debt и подготовить прочную основу для следующих шагов.**

Любое изменение, которое противоречит этому принципу, должно считаться ошибочным, даже если оно выглядит “умным”, “масштабируемым” или “красивым”.