# Канонический мандат рефакторинга `kodex`

Этот документ — главный источник правды для программы рефакторинга. Он описывает не одну локальную волну, а целевую платформу целиком, включая enterprise-заделы, которые должны быть заложены уже в первой версии и не должны потеряться при дальнейшей декомпозиции.

## 1. Неподвижные рамки

### 1.1. Live-safe evolution активной платформы
Платформа уже развёрнута в live-кластере, поэтому активные изменения нельзя считать одноразовыми:
- миграции, секреты, конфиги и deploy path требуют последовательной истории обновлений;
- уже применённые миграции не редактируются; изменения схемы идут новой forward-only additive migration, а destructive/drop/rename выполняется только через отдельный путь `expand -> migrate -> contract`;
- breaking change в `proto`, OpenAPI или AsyncAPI допустим только при согласованном обновлении всех потребителей без live rolling gap; иначе сначала добавляется новое поле или операция, затем переводятся потребители, затем старый контракт удаляется отдельным срезом;
- новые обязательные env/secrets/config требуют staged rollout path или безопасной диагностики, чтобы не ломать старт уже развёрнутого сервиса без явного runbook шага;
- live drift исправляется новой миграцией или управляемым deploy/runbook-шагом, а не ручным SQL и не переписыванием истории.

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

### 1.2. Рефакторинг идёт сверху вниз
Порядок приоритета такой:
1. бизнес-модель и каноническая документация;
2. сервисные и data-заделы;
3. UX и операторские сценарии;
4. runtime/deploy/bootstrap;
5. волны реализации.

### 1.3. Enterprise target фиксируется сразу
Даже если реализация делается поэтапно, документация должна сразу описывать:
- многоорганизационную модель;
- каталоги пакетов;
- контур серверов и кластеров;
- billing;
- release policy;
- automation rules.

Иначе первые волны реализации зацементируют слишком узкую модель и потом заблокируют расширение.

## 2. Основа, которая остаётся неизменной

### 2.1. Kubernetes-first runtime
Платформа работает в Kubernetes и управляет Kubernetes-first execution model:
- под каждую задачу поднимается slot;
- slot в первой версии — отдельный namespace;
- в `code-only` режиме slot содержит pod агента и минимальный рабочий контур;
- в `full-env` режиме slot поднимает рабочее окружение проекта и pod агента с нужным доступом;
- в enterprise-расширении slot может быть не namespace, а nested-cluster.

Для ускорения работы:
- допустим prewarm slots;
- при reuse slot платформа должна уметь переключать ветку, чистить state, выполнять миграции и загружать фикстуры перед новой сессией.

### 2.2. Provider-first рабочая модель
Платформа не подменяет GitHub/GitLab как систему рабочих артефактов.

Базовые принципы:
- работа строится вокруг `Issue`, `PR/MR`, комментариев, mentions и provider relationships;
- review `PR/MR` остаётся у провайдера;
- платформенные состояния — это orchestration, runtime, policy, audit, acceptance, зеркальные проекции и собственные метаданные платформы;
- зеркальная проекция `Issue`, `PR/MR`, комментария или связи нужна для быстрого UI, поиска, уведомлений, приёмки, синхронизации и защиты от лимитов провайдера;
- watermark и открытые разделы остаются переносимым машинным контрактом внутри артефакта провайдера, но не заменяют БД платформы для runtime-состояния, связей с `run`, `job`, slot, рисков и решений приёмки;
- если `Issue` или `PR/MR` создан напрямую у провайдера, webhook или reconciliation создаёт проекцию, а agent-manager дозаполняет обязательные признаки или запрашивает решение человека по policy;
- синхронизация с провайдером строится на трёх слоях: быстрый webhook inbox, обязательный incremental reconciliation с `sync_cursor` и приоритетная проверка горячих сущностей;
- ручная синхронизация допустима только как аварийная админская операция постановки reconciliation job в очередь, а не как штатный пользовательский UX;
- расход лимитов провайдера учитывается детерминированно для операций через `provider-hub` и приближёнными снимками для прямой работы slot-агентов через `gh`;
- все provider-операции проектируются через интерфейсы, где GitHub — первая реализация, GitLab — следующая.

### 2.3. Agent-manager как центр управления
У платформы есть быстрые экземпляры `agent-manager`, через которых:
- пользователь общается с системой через фронтенд, текст и голос;
- обрабатываются mentions и запросы из GitHub/GitLab;
- выбираются flow, роли, шаблоны и следующий шаг;
- запускаются role-агенты и обязательные проверки.

Быстрый `agent-manager` по умолчанию использует дешёвую и быструю модель класса `GPT-5.3-Codex-Spark`, но выбор модели должен быть настраиваемым.

### 2.4. Role-driven flow model
В платформе есть:
- flow;
- stage;
- role;
- `stage role binding`;
- acceptance machine.

Эта модель остаётся центральной и в дальнейшем расширяется automation rules, release policy и пакетными контрактами.

Flow, профили ролей и шаблоны промптов являются платформенной конфигурацией, канонически хранятся в БД и редактируются через UI с версиями, аудитом и policy-проверками.

Репозиторий платформы содержит только установочные фикстуры:
- начальные flow;
- встроенные профили ролей;
- встроенные `work`- и `revise`-шаблоны промптов;
- seed-метаданные для первичной загрузки БД при установке или обновлении платформы.

Агенты в первой версии не редактируют flow, профили ролей и шаблоны промптов. Будущий self-improve для этих объектов должен идти через отдельный контур согласования и публикации новой версии в БД, а не через чтение конфигурации из репозитория при каждом запуске.

### 2.5. Frontend и operator console
Фронтенд полностью переосмысляется:
- стек остаётся;
- UI-библиотека — `PrimeVue`;
- главный рабочий режим — командный центр с чатом и голосом;
- отдельные рабочие пространства нужны для `Issue`, `PR/MR`, `run`, `job` и slot;
- отдельный настроечный контур управляет flow, ролями, каталогами пакетов, доступами, внешними аккаунтами, automation rules и другими policy-объектами.

## 3. Обязательные новые направления wave 5.1

### 3.1. Система плагинов и пакетная платформа
Платформа должна иметь полноценную пакетную модель.

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

Виды пакетов:
- `plugin package` — исполняемое расширение платформы;
- `guidance package` — пакет руководящей документации, шаблонов и правил для агентов.

`Plugin package` должен описываться через manifest в репозитории и включать:
- идентичность, описание, локализованные названия и ссылки на изображения;
- вид пакета;
- версию;
- verification и коммерческий статус;
- требуемые platform APIs;
- обязательные и желательные permissions;
- schema для secret inputs с локализованными названиями, описаниями и типами значений;
- Dockerfile;
- Kubernetes manifests;
- другие runtime-зависимости, необходимые для запуска.

Плагин должен запускаться в Kubernetes-контуре платформы того, кто его установил, и может быть написан на любом языке и стеке.

Примеры, которые сразу должны идти через пакетную платформу:
- Telegram-плагин для согласований;
- Telegram-плагин для обратной связи;
- внешние интеграции для уведомлений, согласований и обратной связи.

Отдельное обязательное решение:
- магазин доступных пакетов не вшивается в ядро платформы;
- мы как авторы поставляем пакет магазина пакетов из приватного репозитория `github.com/codex-k8s/kodex-package-store` и устанавливаем его в свою платформу как обычный пакет;
- другие установки платформы могут использовать наш магазин, свой магазин или только пользовательские источники;
- в приватном репозитории `github.com/codex-k8s/kodex-package-platform-site` должен быть пакет с сайтом платформы и пользовательской документацией платформы: API, разработка пакетов, добавление пакетов в магазин и каталог. Такой сайт должен развиваться и поставляться через пакетную модель.
- source submodule пакетов объявляются в `.gitmodules` и checkout-ятся в `packages/**`;
- метаданные установленных пакетов хранятся в БД платформы и могут предзаполняться из JSON-манифеста внутри репозитория пакета;
- конкретная версия пакета фиксируется gitlink, `tag` или `commit` по контракту пакетной платформы;
- платные пакеты поставляются через прокси платформы и попадают в `packages/**` только после проверки прав;
- downstream-репозитории должны иметь workflow, который удаляет магазин, сайт и необязательные пакеты, не предназначенные для конкретной установки.

### 3.2. Система руководящей документации и каталог пакетов руководящей документации
Руководящая документация должна перестать быть неразделимой частью одного монорепозитория.

Нужно сразу заложить:
- отдельные репозитории руководящей документации;
- отдельный публичный репозиторий шаблонов документации `github.com/codex-k8s/kodex-doc-templates-ru`;
- каталог пакетов руководящей документации;
- модель импорта в проект, репозиторий, сервис или саму платформу;
- работу агента только с локально доступной документацией без векторного хранилища в первой версии.

В частности, должны быть возможны отдельные репозитории для:
- общих руководящих правил, включая `github.com/codex-k8s/kodex-guidelines-common-ru`;
- правил разработки по направлениям/стекам, включая `github.com/codex-k8s/kodex-guidelines-go-backend-ru` и `github.com/codex-k8s/kodex-guidelines-vue-frontend-ru`;
- правил проектирования;
- правил ведения продуктовой документации;
- других руководящих пакетов.

Ключевой принцип:
- пакет руководящей документации живёт в репозитории-источнике;
- в рабочий контур он попадает как локально доступный источник или импорт;
- self-improve задача может запускаться против самого репозитория руководящей документации, а не только против проектного монорепозитория.
- шаблоны документации живут в отдельном публичном репозитории и подключаются как source submodule `docs/templates/**`.

Отдельно от руководящей документации существует проектная документация: продуктовые документы, описания сервисов, архитектурные решения, runbook и договорённости конкретного проекта. Она может жить в одном или нескольких репозиториях проекта и не должна превращаться в пакет руководящей документации только потому, что агенту нужно её читать.

Для проекта с несколькими репозиториями `services.yaml` должен описывать:
- какие репозитории входят в проект;
- где лежит общая продуктовая документация;
- где лежит документация конкретного сервиса;
- какие сервисы зависят от документации других сервисов;
- какие источники документации доступны агенту только для чтения, а какие можно менять в рамках задачи;
- в какие локальные пути рабочего контура эти источники загружаются.

Рабочий контур агента в slot должен получать не только кодовой репозиторий, но и полный разрешённый набор локальных источников: код, проектную документацию, документацию зависимых сервисов и пакеты руководящей документации. Flow, роли и шаблоны промптов передаются агенту как отрендеренный платформой контекст из БД, а не как отдельный набор файлов в workspace.

### 3.3. Организации, группы пользователей и гибкая модель доступа
Платформа должна поддерживать:
- owner-организацию;
- клиентские организации;
- организации внешних исполнителей;
- будущие SaaS-организации.

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

Группы бывают:
- глобальные;
- организационные;
- в будущем допускаются проектные и специальные группы, если они не ломают общую модель.

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

### 3.4. Серверы, кластеры и контур серверов и кластеров
Мы стартуем с одного сервера и одного Kubernetes-кластера, но документация и код больше не должны считать эту топологию единственно возможной.

Нужно сразу заложить:
- реестр серверов;
- реестр Kubernetes-кластеров;
- связи между организациями, проектами, репозиториями и допустимыми серверными и кластерными контурами;
- placement policy;
- подготовку к multi-zone и delegated clusters;
- возможность закреплять проект, репозиторий или отдельный тяжёлый сервис за конкретным кластерным контуром.

### 3.5. Биллинг и cost accounting
Платформа должна сразу проектироваться так, чтобы:
- учитывать затраты на compute, storage и runtime;
- учитывать внешние провайдеры и их стоимость;
- учитывать использование пакетов и в будущем комиссии каталога;
- раскладывать расходы по организациям, проектам и при необходимости по другим контурам;
- формировать основу для invoice и коммерческого учёта.

В enterprise target нужно предусмотреть:
- рублёвый платёжный контур через российские эквайринги;
- валютный контур через `Stripe`;
- выставление счетов организациям, в том числе с разбиением по проектам.

### 3.6. Branch rules, release policy и связь с flow
Платформа должна различать:
- provider-native branches и tags;
- release branches;
- release line или release train;
- release policy;
- политика выкладки;
- release task и release flow.

Нужно заложить модель, где:
- задачи и `PR/MR` попадают в release line;
- релизная ветка и связанные проверки живут у провайдера;
- платформа ведёт policy, gates, стратегию выкладки и операторскую логику;
- можно делать прямой rollout, staged rollout, canary и rollback.

### 3.7. Автозапуск flow по cron и автоматизация по триггерам
Платформа должна уметь:
- запускать flow по расписанию;
- создавать задачи по расписанию;
- реагировать на внешние триггеры;
- запускать специальные agent roles по alerts и operational signals.

Примеры:
- ночной flow для анализа production logs и метрик;
- flow по поиску slow queries;
- триггер на входящий alert от `Prometheus`;
- запуск расследования по превышению порога `500`-ошибок.

Это должно проектироваться как обязательная способность платформы, а не как ad-hoc cron script рядом с платформой.

## 4. Минимальный объём первой версии и enterprise target

| Направление | Минимальный объём первой версии | Enterprise target |
|---|---|---|
| Организации и группы | owner-организация, клиентские организации, участие пользователей и групп, права с областью действия | SaaS-модель с изоляцией по организациям, делегированные администраторы, сложное наследование и исключения |
| Пакетная платформа | встроенные пакеты, пользовательские источники, локальная установка плагинов и пакетов руководящей документации, каталог установленных пакетов, клиентское подключение к магазину доступных пакетов, признак верификации | магазин пакетов как отдельный пакет, верифицированные версии, профили издателей, платные и бесплатные пакеты, распределение выручки |
| Контур серверов и кластеров | один production-кластер с явным слоем реестра и политикой размещения | несколько кластеров, несколько серверов, привязка кластера к организации или проекту, мультизональность |
| Учёт затрат | записи затрат, распределение использования, сводки для биллинга | счета, платёжные провайдеры, биллинг каталога пакетов, автоматическое списание |
| Релизная политика | релизная политика, правила релизных веток, релизная линия, задел для canary и staged rollout | полные программы релизов, политики выкладки с учётом организаций, сложные релизные линии |
| Автоматизация | правила по cron и минимальные триггеры событий | шины событий, переиспользуемые шаблоны автоматизации, сложные графы триггеров |
| Доменные события | outbox/inbox для owner-сервисов, идемпотентная обработка и базовые проекции чтения | управляемый replay, версионирование схем, диагностика подписчиков и межорганизационные политики событий |
| Пакеты руководящей документации | импорт из отдельных репозиториев в локальный рабочий контур | пакеты руководящей документации в магазине, платные и бесплатные наборы, управляемые обновления |
| Flow, роли и шаблоны промптов | каноническое хранение в БД, UI-редактирование, версии, аудит, установочные фикстуры в репозитории платформы | self-improve через согласуемые изменения версий, расширенные политики публикации и делегированное администрирование |
| Проектная документация | ссылки на источники в `services.yaml`, загрузка в workspace и возможность связанного набора `PR/MR` | расширенные политики доступа, проверки доступности и согласованные изменения в нескольких репозиториях |

## 5. Архитектурные следствия

### 5.1. Новые или расширяемые owner-domains
Wave 5.1 означает, что в целевой архитектуре должны быть зафиксированы:
- tenancy-aware `access-manager`;
- расширенный `project-catalog`;
- `package-hub`;
- `fleet-manager`;
- `billing-hub`;
- расширенный `agent-manager` с automation rules;
- расширенный governance-контур для release policy и unattended automation.

### 5.2. Что остаётся во владении провайдера
Даже после этих расширений провайдер остаётся владельцем:
- branches и tags;
- `Issue`, `PR/MR`, comments и review state;
- repository storage.

Платформа не должна плодить внутренние дубликаты там, где достаточно policy, зеркальной проекции и orchestration.

## 6. Что нужно сделать прямо сейчас после wave 6
После завершения чисто документационной wave 6 и до старта wave 7 нужно:
1. провести backlog checkpoint;
2. выровнять GitHub backlog и открытые PR под явные волны 7-17;
3. закрыть или перепривязать устаревшие задачи, которые больше не соответствуют новой канонике;
4. не переходить к кодовым доменным PR до завершения backlog checkpoint;
5. после backlog checkpoint открыть первую кодовую доменную волну — wave 7 `Access and accounts`.
6. перед кодовой реализацией wave 7 пересобрать минимальную новую `docs/**` по `refactoring/24-pre-wave7-documentation-rebuild-plan.md`.

### 6.1. Результат checkpoint
Backlog checkpoint выполнен и должен считаться частью текущего рабочего состояния программы:
- отдельный пакет checkpoint зафиксирован в `refactoring/23-backlog-checkpoint-before-wave7.md`;
- первая кодовая очередь wave 7 открыта отдельными issues `#599`, `#600`, `#601`, `#602`;
- устаревшие issues старых execution chains больше не должны использоваться как shortcut для запуска wave 7;
- следующая управленческая точка входа после merge checkpoint-пакета — пересборка минимальной новой `docs/**`, затем первая кодовая реализация wave 7.

## 7. Явная декомпозиция волн реализации после wave 6
После завершения чисто документационной wave 6 реализация идёт не одной длинной фазой, а явными последовательными волнами:

1. Волна 7: Access and accounts
   - доступ, организации, группы, пользователи и внешние аккаунты;
   - идёт первой, потому что многоорганизационная модель и модель доступа влияют на все остальные домены.

2. Волна 8: Projects and repositories
   - проекты, репозитории, релизные политики и источники проектной документации;
   - идёт сразу после доступа, потому что почти вся работа платформы якорится в проектном контуре.

3. Волна 9: Package platform
   - пакеты, каталоги, установка, версии, пакеты руководящей документации;
   - идёт до оркестрации, чтобы flow и агентные роли опирались на уже канонический пакетный слой.

4. Волна 10: Provider-native work items
   - `Issue`, `PR/MR`, comments, relationships, ветки и теги;
   - идёт до оркестрации, потому что именно вокруг provider-native сущностей строится рабочая модель платформы.

5. Волна 11: Agent orchestration
   - `agent-manager`, flow, stage, role, шаблоны промптов и automation rules;
   - идёт после проектного, провайдерного и пакетного основания, чтобы не проектировать оркестрацию в пустоте.

6. Волна 12: Runtime and fleet
   - слоты, `run`, `job`, runtime manager, fleet manager, серверы и кластеры;
   - идёт после оркестрации, потому что runtime должен исполнять уже зафиксированную рабочую модель.

7. Волна 13: Interaction hub
   - платформенный MCP, согласования, уведомления, внешняя обратная связь и каналы взаимодействия;
   - идёт после runtime-контура и оркестрации, потому что должна опираться на реальные состояния исполнений и gate-решений.

8. Волна 14: Console and operations UX
   - реализация утверждённых операторских экранов и рабочих пространств;
   - идёт поверх уже реализованных базовых и операционных доменов, а не как параллельная декоративная ветка.

9. Волна 15: Risk and release governance
   - risk gates, release lines, branch rules и автоматизация по триггерам;
   - идёт после провайдерного контура, оркестрации, runtime и операторского UX, потому что связывает их в релизный контур.

10. Волна 16: Billing and cost accounting
   - затраты, распределение расходов, счета и коммерческий контур;
   - идёт после runtime, пакетной платформы и многоорганизационного контура, потому что использует их данные как источник фактического учёта.

11. Волна 17: Knowledge lifecycle
   - руководящая и проектная документация, самоулучшение и жизненный цикл знаний;
   - идёт последней в этом ряду, потому что должна опираться на уже реализованные пакетный, проектный и контуры оркестрации.

Backlog checkpoint не считается отдельной волной, но обязателен сразу после wave 6 и до wave 7.

## 8. Что нельзя потерять после сжатия контекста
Если контекст сессии будет сокращён, обязательными для восстановления картины остаются следующие идеи:
1. пакетная платформа = общий слой для плагинов и пакетов руководящей документации;
2. организации и группы закладываются сразу, даже если MVP прост;
3. один сервер и один cluster — это только стартовая операционная конфигурация;
4. billing и cost accounting нужно проектировать сейчас, а не после MVP;
5. release branches, release policy, release trains и стратегия выкладки — часть канонической модели;
6. automation rules по cron и trigger-driven events — часть flow model;
7. пакеты руководящей документации должны жить в репозиториях-источниках и попадать в рабочий контур локально;
8. flow, роли и шаблоны промптов канонически хранятся в БД, редактируются через UI и загружаются из репозиторных фикстур только при установке или seed-обновлении;
9. проектная документация описывается источниками в `services.yaml` и загружается агенту локально вместе с кодом и руководящими пакетами;
10. всё это должно быть отражено в волнах 0-6 до старта кодовых волн реализации;
11. после wave 6 реализация идёт явными волнами 7-17, а не безразмерной фазой `Wave 7+`;
12. между wave 6 и wave 7 обязательно выполняется backlog checkpoint с выравниванием GitHub backlog.
13. перед первой кодовой реализацией новой волны конфликтующие устаревшие код и документация выводятся из активной каноники: код не дорабатывается как база новой версии, а устаревшие материалы остаются только в `deprecated/**`.
14. перед кодовой wave 7 новая проектная документация создаётся с нуля по `docs/templates/**` в структуре `docs/platform/**`, `docs/domains/**`, `docs/catalogs/**`, `docs/delivery/**`, `docs/research/**`; старые домены доступны только в `deprecated/docs/**`.
15. карту связей `Issue/PR ↔ документы` нельзя вести одним большим файлом: использовать раздельные файлы `docs/delivery/issue-map/domains/*.md` и `docs/delivery/issue-map/waves/*.md`.
16. магазин доступных пакетов является устанавливаемым пакетом из репозитория-источника, а не жёстко встроенной частью ядра; пакетная платформа выступает клиентом магазина и владельцем локального состояния установки; наш авторский магазин живёт в приватном репозитории, а сайт и пользовательская документация платформы поставляются отдельным пакетом из отдельного репозитория.
17. межсервисная синхронизация строится на доменных событиях: owner-сервис публикует факт изменения через надёжный outbox, потребители обрабатывают событие идемпотентно и сами решают, что делать по своей бизнес-логике без `FOREIGN KEY`, cross-database join и каскадных операций с таблицами чужого домена.
