---
doc_id: REF-CK8S-0001
type: charter
title: "kodex — charter программы полного рефакторинга"
status: active
owner_role: EM
created_at: 2026-04-21
updated_at: 2026-04-23
related_issues: [470, 488]
related_prs: []
approvals:
  required: ["Owner"]
  status: approved
  request_id: "owner-2026-04-21-refactoring-wave0"
  approved_by: "ai-da-stas"
  approved_at: 2026-04-21
---

# Charter программы полного рефакторинга

## Проблема
Текущая версия `kodex` выросла вокруг старой control-plane-центричной модели, где слишком много решений завязано на собственные платформенные сущности, stage-лейблы и исторический delivery-процесс. Новый мандат требует переосмыслить платформу как систему управления агентной работой поверх provider-native сущностей и runtime-платформы, без сохранения устаревшего легаси.

## Цели
1. Сформировать новую каноническую модель платформы на уровне бизнеса, процессов, данных и UX.
2. Перейти к provider-first подходу:
   - инициатива = обычный `Issue` со своим типом;
   - работа ведётся вокруг `Issue`, `PR/MR`, комментариев, mentions и provider relationships;
   - платформа хранит только enrichments, watermarks, runtime state и policy state.
3. Выделить понятные домены и переписывать их вертикальными срезами.
4. Отказаться от архитектурного и документационного шума сразу после появления новой каноники.
5. Подготовить путь к развёртыванию новой версии платформы на новом чистом сервере, но только после появления минимально жизнеспособного вертикального среза.

## Неподвижные решения программы
- Старую control-plane-модель не поддерживаем как отдельный продуктовый слой, но live-кластер уже
  существует: миграции, транспортные контракты, env/secrets/config и deploy path меняются только
  через safe staged sequence.
- Старый код и старая документация не сохраняются "на всякий случай".
- `Issue` и `PR/MR` остаются главными рабочими сущностями; отдельную "инициативу" как внутреннюю work-entity не создаём.
- Поддерживается Kubernetes-only runtime.
- GitHub остаётся первым провайдером, GitLab проектируется сразу через интерфейсы и provider contracts.
- В центре пользовательского опыта будет не dashboard из произвольных сущностей, а agent-manager с чатовым и голосовым управлением.
- Внешние каналы взаимодействия не фиксируются жёстким списком: нужен расширяемый контракт для подключения новых каналов.
- Enterprise seams по package platform, organizations и groups, fleet, billing, release policy и automation rules закладываются сразу, даже если implementation floors этих направлений будут поэтапными.

## Что не входит в первую волну
- Немедленная реализация новой архитектуры в коде.
- Немедленное развёртывание на новый сервер.
- Немедленный выбор конкретной plugin/adapters архитектуры для внешних каналов без отдельного сравнения вариантов.

## Принципы поставки
- Один PR = один понятный срез.
- Большие идеи можно быстро проверять прототипами, но production-путь обязан раскладываться на компактные PR.
- Если в ветке/PR появляется новая модель домена, старая модель этого же сценария должна быть объявлена устаревшей и поставлена в очередь на удаление.
- Если начинается первая кодовая реализация новой волны, конфликтующие устаревшие код и документация должны быть сразу выведены из активной каноники и переведены в `deprecated/**` или справочный пакет.
- В каждой волне одновременно обновляются:
  - канонические документы программы;
  - затронутые инструкции;
  - backlog-аудит;
  - план следующего среза.

## Когда начинать deploy на новый сервер
Не раньше, чем будут зафиксированы и частично реализованы все элементы минимального вертикального среза:
1. аутентификация и пользователи;
2. проекты и репозитории;
3. GitHub integration + webhook ingest + mention handling;
4. agent-manager session loop;
5. хотя бы один рабочий flow;
6. code-only slot и один full-env slot;
7. базовый UI с центральным чатом, запуском задачи и операционным статусом.

До этого момента инфраструктурная работа ограничивается документированием target topology и подготовкой bootstrap/deploy strategy.
