# Мандат для ИИ-агента

Этот документ задает не рекомендации, а обязательные правила выполнения рефакторинга.

## 1. Главная цель

Цель не в том, чтобы "аккуратно сохранить старое". Цель в том, чтобы быстро и последовательно превратить текущий Control Plane из неявного монолита в понятный набор доменных сервисов с прозрачным ownership.

Платформа уже развёрнута в live-кластере. Значит:
- устаревшая control-plane-модель не сохраняется как самостоятельная продуктовая цель;
- внутренние контракты, `proto`, миграции и расположение кода можно менять быстро, но только через safe staged sequence для live-кластера;
- уже применённые миграции не редактируются; destructive/drop/rename идут через `expand -> migrate -> contract`;
- breaking change в `proto`, OpenAPI или AsyncAPI допустим только если все потребители обновляются в согласованном срезе без live rolling gap;
- старую и новую модель нельзя держать параллельно дольше, чем требуется для staged cutover и явно заведённого следующего среза удаления.

## 2. Неоспоримые правила

### 2.1. Правило "add new - cut over safely - remove old"

Если в PR появился новый сервис, новый gRPC метод, новая таблица, новый пакет или новый поток выполнения, старое решение для того же сценария по умолчанию удаляется в этом же PR.

Если live-safe sequence не позволяет удалить старое в том же PR, применяется staged cutover:
1. `expand`: добавить новый путь рядом со старым без поломки текущих потребителей;
2. `migrate`: перевести потребителей и данные на новый путь;
3. `contract`: удалить старый путь отдельным коротким срезом.

Допускается временный adapter или shim только если одновременно выполняются все условия:
- он нужен для атомарного cutover внутри одного PR или для короткого staged cutover live-кластера;
- он локальный и короткоживущий;
- он помечен как transitional;
- он удаляется в этом же PR или в заранее объявленном следующем PR, который уже создан в GitHub Issues.

Запрещено:
- оставлять старый код "на всякий случай";
- плодить feature flags без явного срока удаления;
- держать два источника истины по одному доменному сценарию;
- переносить только запись, но не переносить чтение, если это создает постоянную dual-path схему.

### 2.2. Правило владения данными

У каждого сервиса - своя база данных:
- сервер или кластер Postgres может быть общим;
- database name у каждого сервиса свой;
- credentials у каждого сервиса свои;
- runtime user сервиса имеет доступ только к своей базе.

Запрещено:
- читать чужие таблицы напрямую;
- писать в чужую БД напрямую;
- выполнять cross-database join между доменами;
- использовать shared repository package, который скрывает доступ к чужим данным.

### 2.3. Правило доступа к данным только через сервис-владельца

Любая операция над данными другого домена делается только через gRPC API сервиса-владельца.

Примеры:
- Runtime Deploy Service не читает `agent_runs` напрямую - он спрашивает Run Orchestrator Service.
- Mission Control Service не читает `repositories` напрямую - он спрашивает Project Catalog Service.
- Interactions Service не читает `users` напрямую - он спрашивает Platform Admin & IAM Service.

### 2.4. Правило документации

Каждый PR обязан обновлять документацию одновременно с кодом. Обновлению подлежат:
- архитектурные markdown-файлы;
- продуктовые markdown-файлы;
- ADR;
- README конкретного сервиса;
- диаграммы, если изменились потоки или ownership.

PR без актуальной документации считается незавершенным.

### 2.5. Правило актуализации Issues

Перед началом первого этапа агент обязан:
- проанализировать open Issues, active PRs и уже заведенные инициативы;
- разложить их по bounded contexts;
- определить, какие Issues уже неактуальны, дублируются или конфликтуют;
- обновить дорожную карту на основе фактического состояния backlog.

После этого перед каждым следующим этапом агент снова синхронизирует план и Issues.

## 3. Что считается успехом

Успех - это не только выделенные папки или новые бинарники. Успех означает, что для каждого домена одновременно выполнены все условия:
- есть один владелец сервиса;
- есть один владелец БД;
- есть один владелец gRPC контракта;
- старый путь удален;
- все вызовы переведены на новый сервис;
- документация и Issues обновлены.

## 4. Что делать нельзя

Нельзя:
- строить долгоживущий compatibility gateway как новый центр монолита;
- выносить код без реального ownership данных;
- создавать "общую платформенную библиотеку" с бизнес-логикой разных доменов;
- оставлять shared DB как постоянное решение;
- переносить только транспортный слой без переноса бизнес-инвариантов;
- создавать новый сервис без отдельной базы и без четкого proto контракта;
- закрывать этап без удаления legacy-кода.

## 5. Разрешенная переходная модель

Короткая переходная модель допустима только в таком виде:
- новый сервис поднимается;
- его БД и миграции создаются;
- все вызывающие участки меняются на новый gRPC контракт;
- данные переносятся или инициализируются;
- старые handlers, репозитории и таблицы удаляются или выводятся из использования;
- документация и Issues обновляются в том же цикле.

Это означает, что допустимы короткие "bridge" решения, но недопустимы длинные "parallel run" решения.
