---
doc_id: REF-CK8S-0006
type: product-model
title: "kodex — каноническая продуктовая модель новой платформы"
status: active
owner_role: PM
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-wave1"
  approved_by: "ai-da-stas"
  approved_at: 2026-04-21
---

# Каноническая продуктовая модель новой платформы

## TL;DR
- `kodex` проектируется как платформа управления агентной работой поверх нативных сущностей провайдера и Kubernetes-окружений.
- Главные рабочие сущности остаются внешними: `Issue`, `PR/MR`, комментарии, mentions и provider relationships.
- Внутри платформы создаются только те сущности, которых нет у провайдера: проекты, репозитории, организации, группы, flow-шаблоны, агентные сессии, запуски, слоты, платформенные `job`, каталог пакетов, биллинг, контур серверов и кластеров и состояния политик.
- Инициатива не является отдельной внутренней рабочей сущностью: это обычный `Issue` типа `initiative`.
- Центральная точка взаимодействия с платформой для пользователя: agent-manager, доступный через фронтенд, голосовой интерфейс и внешние каналы по расширяемому контракту.
- Встроенные и пользовательские роли описываются через профиль роли, а flow и шаблоны промптов канонически хранятся в БД платформы с версиями, аудитом и установочными фикстурами в репозитории платформы.
- Текстовый и голосовой диалог с agent-manager, а также временные медиа-вложения проектируются как обязательная продуктовая функциональность, но бинарные объекты не превращаются в содержимое PostgreSQL.
- Плагины и руководящие пакеты документации проектируются как разные виды общего пакетного контракта, где одни пакеты исполняются в Kubernetes, а другие импортируются в локальный рабочий контур.
- Проектная документация является отдельным классом репозиторного содержимого проекта: она описывается в `services.yaml`, загружается агенту локально в workspace и может изменяться в нескольких репозиториях в рамках одной задачи.

## 1. Продуктовая цель
Платформа должна позволять владельцу продукта и команде вести разработку, проверки, релизы и эксплуатационные действия через управляемую цепочку агентов, не отрываясь от привычных сущностей GitHub/GitLab и не плодя внутри платформы дублирующий рабочий мир.

Новая модель должна решать сразу четыре задачи:
1. Давать понятный управляющий слой поверх `Issue` и `PR/MR`.
2. Запускать агентную работу по flow и по прямым запросам пользователя.
3. Поднимать нужное runtime-окружение в Kubernetes под конкретную работу.
4. Фиксировать трассируемость, риски, апрувы и evidence без ручной бюрократии.

## 2. Главный принцип модели
Платформа не заменяет GitHub/GitLab как систему рабочих артефактов. Она добавляет поверх них:
- оркестрацию;
- runtime-контур;
- policy-контур;
- traceability;
- audit;
- контур взаимодействия.

Из этого следуют базовые решения:
- если сущностью удобно и нативно управлять в GitHub/GitLab, платформа не создаёт для неё дубликат;
- если сущность нужна только для внутренней координации, аудита, запуска и безопасности, она живёт в платформе;
- flow не должен требовать от пользователя знания внутренней реализации платформы.

## 3. Канонические участники

### Пользователь платформы
Человек, который управляет проектами, запускает работу, принимает продуктовые решения и получает обратную связь от платформы.

### Владелец продукта (`Owner`)
Отдельная роль пользователя, которая утверждает продуктовые документы, архитектурные решения, high-risk переходы и go/no-go на релиз.

### Агент-менеджер (`agent-manager`)
Центральный платформенный агент, через которого пользователь взаимодействует с системой. Он:
- разбирает запрос;
- определяет намерение;
- выбирает flow или прямой запуск;
- выбирает встроенную или пользовательскую роль;
- подбирает шаблон выполнения работы и, если требуется, шаблон устранения замечаний;
- назначает одного или несколько ролевых агентов;
- следит за обязательными полями, watermark и контрактом приёмки;
- возвращает пользователю следующий шаг или блокировку.

Базовый операционный режим agent-manager:
- быстрые экземпляры agent-manager работают через платформенный MCP-сервер;
- они получают через него актуальные данные платформы и запускают разрешённые операции;
- они не должны для обычной платформенной работы зависеть от долгого slot-окружения и shell-first сценариев.

### Ролевой агент
Специализированный агент под конкретную роль: аналитика, архитектура, разработка, тестирование, эксплуатация, управление знаниями и другие системные или пользовательские роли.

Для роли задаются:
- область действия и ключ роли;
- обязательный шаблон выполнения работы;
- необязательный шаблон устранения замечаний;
- режим исполнения;
- политика доступа к MCP, внешним аккаунтам и runtime;
- правила участия в flow как основного исполнителя, роли проверки или дополнительной контрольной роли.

### Машина приёмки (`acceptance machine`)
Платформенный контур приёмки, который проверяет, что агент:
- создал нужные артефакты;
- заполнил обязательные поля;
- корректно оформил watermark и открытые инструкции;
- не нарушил policy перед переходом к следующему шагу.

Машина приёмки не заменяет review и approval, но не позволяет молча пропустить недозаполненный артефакт.

## 4. Канонические сущности платформы

### 4.1. Управленческие сущности платформы

#### Проект
Контейнер доступа, настроек, репозиториев, flow-политик, внешних аккаунтов и runtime-ограничений.

Проект может включать один или несколько репозиториев. Репозитории внутри проекта могут выполнять разные роли: код сервиса, общая проектная документация, документация конкретного сервиса, инфраструктурные шаблоны или иные файлы, которыми нужно управлять через provider-native `PR/MR`.

#### Репозиторий
Привязанный репозиторий или путь в монорепозитории, где живут код, проектная документация, конфигурация или иной управляемый контент проекта.

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

#### Установочные фикстуры flow, ролей и шаблонов промптов
Репозиторий платформы содержит seed-файлы, из которых при установке или обновлении загружаются встроенные flow, профили ролей, шаблоны промптов и связанные policy-описания.

Эти файлы не являются runtime-источником истины. После загрузки каноническая версия живёт в БД платформы и меняется через UI с аудитом и policy-проверками.

#### Источник проектной документации
Описанный в `services.yaml` источник продуктовой или сервисной документации проекта.

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

#### Граф проектной документации
Набор источников проектной документации и зависимостей между ними.

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

#### Организация
Контейнер tenancy-модели, который объединяет пользователей, группы, проекты, контур биллинга и допустимые инфраструктурные контуры.

#### Группа пользователей
Логическая группа для назначения прав, подписок и policy без прямой привязки каждого правила к одному пользователю.

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

#### Каталог пакетов
Платформенный каталог записей о пакетах, через который публикуются, верифицируются, устанавливаются и обновляются расширения платформы.

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

#### Запись каталога пакетов
Каноническая запись каталога, которая описывает один пакет и его версии.

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

#### Пакет-плагин (`plugin package`)
Исполняемое расширение платформы.

Пакет-плагин поставляет:
- manifest;
- Dockerfile;
- Kubernetes manifests;
- описание возможностей пакета;
- список требуемых platform APIs;
- required и optional permissions;
- schema секретов и их локализованные описания;
- операционные требования к runtime и интеграциям.

#### Пакет руководящей документации (`guidance package`)
Пакет руководящей документации, шаблонов и правил для агентов.

Он:
- хранится в репозитории-источнике;
- импортируется в локальный рабочий контур платформы, проекта, репозитория или сервиса;
- может подключаться на уровне платформы, организации, проекта, репозитория или отдельного сервиса, если это допускает политика использования пакета;
- используется агентом по локальным файлам, без обязательного vector storage;
- может быть выкачан в отдельный локальный путь рабочего контура, чтобы код и руководящая документация жили рядом, но в разных репозиториях;
- допускает self-improve задачи против самого репозитория с руководящей документацией.

#### Flow-шаблон
Описание стандартного пути выполнения работы:
- какие типы задач создаются;
- какие этапы обязательны;
- какие артефакты ожидаются на выходе этапа;
- какие переходы автоматические, а какие требуют `gate` или Human gate;
- какие привязки ролей к этапам обязательны;
- какие дополнительные роли подключаются как параллельный контур проверки и контроля;
- какие automation rules могут запускать flow автоматически.

Каноническое описание flow хранится в БД платформы. Для flow фиксируются версия, digest, область применения, состояние проверки, аудит изменений и связь с установочной фикстурой, если версия была загружена из репозитория платформы.

#### Шаблон этапа flow
Элемент flow-шаблона, который описывает один конкретный этап:
- ключ и название этапа;
- тип создаваемой или ожидаемой задачи;
- обязательные артефакты;
- acceptance profile;
- `gate` и Human gate;
- runtime-политику;
- правила перехода и follow-up.

#### Привязка роли к этапу (`stage role binding`)
Отдельная сущность конфигурации, которая описывает, как конкретная роль участвует в конкретном этапе flow.

Именно `stage role binding`, а не профиль роли, задаёт:
- запускается ли роль на этапе вообще;
- является ли она основным исполнителем;
- работает ли она как роль проверки;
- работает ли она как `gatekeeper`;
- запускается ли она автоматически, параллельно, последовательно или вручную;
- обязателен ли её результат для перехода дальше.

#### Профиль роли агента
Описание встроенной или пользовательской роли, которое задаёт:
- ключ роли и область действия;
- обязательный шаблон выполнения работы;
- необязательный шаблон устранения замечаний;
- режим исполнения, допустимый контур запуска и политику переиспользования slot;
- политику доступа к MCP, внешним аккаунтам и runtime;
- допустимые режимы участия в `stage role binding`.

Для части ролей профиль должен явно разрешать не только обычный `code-only` или `full-env`, но и:
- переиспользование уже занятого slot;
- запуск в production-контуре только для чтения, если роль относится к `qa`, мониторингу, проверке релиза или postdeploy-наблюдению и не должна менять production напрямую.

Профиль роли ссылается на версии `work`- и `revise`-шаблонов промптов в БД и хранит связанные policy-поля. Канонический текст шаблонов не читается из репозитория при запуске агента.

#### Release policy
Платформенная политика ветвления и релизов, которая описывает:
- как формируются release branches или иные release contours;
- какие gates и evidence обязательны;
- какая политика выкладки применяется;
- как flow связывается с релизной линией и выкладкой.

#### Release line
Платформенный объект координации релизной поставки, который связывает provider-native ветки и теги с набором задач, `PR/MR`, релизных решений и действий по выкладке.

#### Automation rule
Правило автоматического запуска, которое описывает:
- расписание;
- событие-триггер;
- целевой flow или тип создаваемой задачи;
- контур действия;
- risk и approval policy;
- ограничения по проекту, репозиторию, организации или окружению.

#### Агентная сессия
Логическая сессия агента-менеджера или ролевого агента с историей взаимодействия и возможностью продолжения.

#### Запуск (`run`)
Отдельное исполняемое действие агента в рамках сессии и задачи.

#### Слот (`slot`)
Изолированное Kubernetes-окружение для выполнения работы.

#### Сервер
Узел размещения платформы или управляемый внешний узел, который участвует в реестре серверов и кластеров.

#### Kubernetes-кластер
Описанный в платформе runtime-контур, на котором могут жить:
- сама платформа;
- slots;
- плагины;
- проектные окружения;
- в будущем delegated или tenant-specific workloads.

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

#### Нода кластера
Вычислительный узел Kubernetes-кластера, который может быть связан с конкретным сервером или иной машиной в инфраструктурном контуре.

#### Placement policy
Правило, по которому организация, проект, репозиторий, пакет или конкретный runtime выбирают допустимый серверный или кластерный контур.

#### Платформенная job (`job`)
Отдельная системная операция платформы, которая выполняет технический шаг жизненного цикла среды или поставки.

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

`Job` не равна агентному запуску:
- `run` описывает работу агента;
- `job` описывает техническое выполнение build/deploy/mirror шага.

#### Внешний аккаунт
Учётная запись внешней системы, которую платформа использует для работы:
- GitHub/GitLab;
- Codex/OpenAI и другие провайдеры моделей;
- внешние каналы уведомлений и обратной связи.

#### Billing account
Платформенная сущность коммерческого контура, которая связывает организацию, проектный контур, поставщиков стоимости и правила расчёта.

#### Cost record
Каноническая запись учёта затрат по runtime, использованию внешних провайдеров, пакетам или другим платным операциям.

#### Invoice basis
Платформенно сформированный расчётный срез, на основе которого можно выставить счёт организации или проекту.

#### Платформенный MCP-сервер
Инструментальный слой платформы, через который agent-manager и slot-агенты получают доступ к:
- актуальным данным owner-сервисов;
- platform-owned операциям;
- approval и feedback-контуру;
- платформенным служебным действиям с аудитом и policy-проверкой.

Платформенный MCP-сервер не создаёт собственную доменную модель и не подменяет сервисы-владельцы.

### 4.2. Нативные рабочие сущности провайдера

#### `Issue`
Базовая единица работы. Через тип, labels, relationships и body-политику она описывает:
- инициативу;
- этапную задачу;
- follow-up задачу;
- риск;
- инцидент;
- операционное действие.

#### `PR/MR`
Основной артефакт изменения кода, документации или конфигурации.

#### Комментарий
Носитель обратной связи, уточнений, вызова агента через mention и публикации машинно-сгенерированного результата.

#### Mention
Нативный способ прямого запуска взаимодействия с платформой в GitHub/GitLab через `@bot`.

#### Relationship
Связи между задачами и `PR/MR`: блокирует, продолжает, закрывает, связан с этапом, связан с риском и другие нативные или платформенно-обогащённые связи.

## 5. Базовая рабочая модель

### 5.1. Инициатива
Инициатива = `Issue` типа `initiative`.

Она описывает крупную цель или поток работ и может:
- запускать flow;
- порождать follow-up задачи следующих этапов;
- быть родительской задачей для связанных `Issue` и `PR/MR`.

Платформа не создаёт отдельную сущность `Initiative` в БД как параллельный рабочий объект.

### 5.2. Этапная задача
Этапная задача = `Issue` специального рабочего типа, который соответствует этапу flow:
- `intake`;
- `vision`;
- `prd`;
- `arch`;
- `design`;
- `plan`;
- `dev`;
- `qa`;
- `release`;
- `postdeploy`;
- `ops`;
- другие типы, явно разрешённые policy проекта.

### 5.3. Follow-up задача
Обычный `Issue`, создаваемый агентом как следующий шаг процесса или как дополнительное действие по результату проверки, релиза, инцидента или product/technical review.

### 5.4. Артефакт этапа
В первой канонической модели обязательными артефактами считаются:
- `Issue`;
- `PR/MR`;
- комментарий с решением, вопросом или запросом уточнения.

Файлы документации живут в репозиториях проекта, но не рассматриваются как отдельная первичная рабочая сущность платформы. Они входят в evidence и контур проверки через `Issue`, `PR/MR` и связанные комментарии.

Если задача меняет несколько репозиториев, результатом считается связанный набор `PR/MR`, а не один обязательный `PR/MR`. Платформа должна уметь связать такие `PR/MR` с одной задачей, одним run и одним acceptance-контуром.

Для release, postdeploy, `qa` и мониторинговых ролей допустимы разные комбинации выходных артефактов:
- структурированный комментарий под release-задачей или `PR/MR`;
- `PR/MR` с отчётом, документацией или результатами наблюдения;
- follow-up `Issue` на устранение дефекта, дополнительную проверку или откат релиза.

### 5.5. Встроенные и пользовательские роли
Базовые роли поставляются вместе с платформой и считаются встроенными.

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

Платформа также должна поддерживать пользовательские роли, которые:
- добавляются без переписывания ядра;
- могут использоваться в flow наравне со встроенными;
- могут быть привязаны к этапам как исполнители, роли проверки, `gatekeeper` или вспомогательные роли;
- проходят тот же контур проверки, что и встроенные правила платформы.

Сам факт участия конкретной роли в конкретном этапе задаётся не профилем роли, а `stage role binding` внутри flow.

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

Минимальный ожидаемый набор таких ролей:
- reviewer;
- `qa`;
- release-check;
- postdeploy-наблюдатель;
- роль управления рисками.

Роль управления рисками является встроенной профильной ролью платформы.

Её базовое назначение:
- анализировать diff, артефакты и policy-контекст именно с точки зрения риска;
- участвовать как дополнительная контрольная роль на переходах, где flow или policy требуют усиленного risk-контурa;
- рекомендовать повышение класса риска и запуск дополнительных ролей проверки;
- не понижать класс риска без явного человеческого решения.

Детальная семантика изменения класса риска, история таких изменений и связь с human gates фиксируются не здесь, а в wave 4 `risk/release governance`.

Канонический текст шаблонов промптов для встроенных и пользовательских ролей хранится в БД.

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

## 6. Как запускается работа

### Запуск из фронтенда
Пользователь обращается к agent-manager через центральный чат, голос или структурированное действие во фронтенде.

### Запуск из GitHub/GitLab
Работа может быть запущена:
- созданием `Issue` с нужным типом и параметрами;
- комментарием с mention бота;
- комментарием в `PR/MR`;
- машинным переходом из предыдущего этапа flow.

### Запуск по flow
Пользователь не обязан помнить технические детали запуска. Он может сказать:
- что хочет получить;
- какой flow выбрать;
- какой риск/режим допустим;
- нужно ли полное runtime-окружение.

Дальше agent-manager сам формирует нужные артефакты и запускает следующий шаг.

Если flow того требует, на одном этапе и на одном переходе могут запускаться несколько ролей через `stage role binding`:
- основной исполнитель этапа (`executor`);
- роль проверки (`checker`);
- `gatekeeper`;
- вспомогательная роль (`auxiliary`);
- специальные роли контроля качества текста, документации или policy.

При этом agent-manager по умолчанию:
- получает платформенные данные через платформенный MCP-сервер;
- инициирует платформенные операции через тот же MCP-контур;
- при необходимости создаёт или обновляет provider-native артефакты через `provider-hub` и связанные инструменты платформы.

## 7. Агент-менеджер как центр продукта
Агент-менеджер становится главным управляющим интерфейсом платформы.

Он обязан:
- понимать запросы пользователя на естественном языке;
- работать и через фронтенд, и через внешние каналы, и через текстовый/голосовой диалог;
- уметь инициировать новые задачи и продолжать существующие;
- выбирать встроенную или пользовательскую роль, соответствующий flow и нужный `work`/`revise` шаблон;
- запускать дополнительные роли проверки и контроля, если этого требует этап или acceptance profile;
- объяснять, что происходит и почему;
- останавливать процесс, если не хватает обязательных данных, апрува или внешних лимитов.

Базовая модель по умолчанию для агента-менеджера проектируется как быстрая и дешёвая. На текущем этапе базовым значением считается `gpt-5.3-codex-spark`, но выбор должен остаться настраиваемым.

## 8. Runtime как часть продукта
Платформа не просто создаёт задачи. Она должна уметь:
- поднимать `code-only` slot;
- поднимать `full-env` slot;
- переиспользовать заранее прогретые слоты;
- давать отдельным ролям ограниченный запуск в production-контуре только для чтения;
- готовить среду под продолжение сессии;
- управлять техническими `job`, которые собирают и выкладывают окружение;
- в будущем поддержать nested-cluster режим для enterprise-сценариев.

Runtime не является необязательной подсистемой. Это часть базовой ценности продукта.

## 9. Platform jobs как часть поставки и среды
Платформа обязана явно различать агентную работу и техническую работу среды.

Для этого вводится отдельная сущность `job`, которая отражает:
- какой технический шаг выполняется;
- к какому проекту, репозиторию, slot, delivery-stage или production-деплою относится операция;
- какой входной артефакт и какая цель у операции;
- текущий статус, время запуска, время завершения и причину ошибки;
- ссылку на Kubernetes job/pod или иной runtime-исполнитель.

Базовая цепочка технической поставки остаётся такой:
1. зеркалирование внешних зависимостей, если это требуется;
2. сборка и сохранение образов в реестр, если это требуется;
3. деплой в slot или в production.

Эти шаги должны быть видимыми как отдельные `job`, а не растворяться внутри agent-manager или скрытого control-plane процесса.

### Регламентные `job`
Кроме build/deploy-контура платформа должна поддерживать и регламентные `job`, которые запускаются периодически по policy.

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

Важно:
- это не новый отдельный класс сущностей;
- это те же `platform jobs`, только другого типа и расписания.

### Внешние системы остаются владельцами своих сущностей
Платформа не должна создавать собственные внутренние сущности ради контроля того, чем уже владеет внешняя система.

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

### Наблюдаемость и сбои `job`
Если периодическая или ручная `job` падает, это должно быть видно оператору не хуже, чем сбой build/deploy шага.

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

Если cleanup или иная регламентная `job` перестала успешно выполняться, это не должно теряться внутри Kubernetes.

## 10. Что хранится внутри платформы, а что нет

### Платформа хранит
- сведения о проектах и репозиториях;
- flow, версии flow и результаты проверки правил;
- профили ролей, их политики исполнения и ссылки на версии шаблонов промптов;
- тексты и версии `work`- и `revise`-шаблонов промптов;
- агентные сессии и запуски;
- текстовые диалоги, краткие статус-отчёты и ссылки на временные медиа-вложения;
- состояние слотов;
- сведения о платформенных `job`;
- реестр внешних аккаунтов;
- audit;
- состояние рисков;
- состояние приёмки;
- зеркальные проекции, состояние дозаполнения и платформенные метаданные по артефактам провайдера;
- метаинформацию watermark и решения policy-контура.

### Что хранится по `job`
По каждой технической `job` платформа должна хранить минимум:
- тип операции;
- связанный проект, репозиторий, slot или production-контур;
- входной build/deploy context;
- статус и итог;
- timestamps;
- информацию о расписании, если `job` периодическая;
- причину ошибки;
- короткий хвост последних записей лога для быстрого просмотра в UI и API.

Полный лог `job` не должен считаться обязательной частью PostgreSQL-модели первой версии.
Сырые логи остаются в Kubernetes-контуре и в будущем могут быть отданы в централизованную систему логирования.

### Уведомления как обязательный задел
Платформа должна иметь настраиваемый контур уведомлений.

На текущем уровне фиксируется только обязательный минимум:
- уведомления об ошибках agent run и платформенных `job`;
- уведомления о завершении важных задач и этапов;
- уведомления о необходимости действия человека;
- уведомления о проблемах с лимитами и внешними зависимостями.

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

### Платформа не должна дублировать
- полный жизненный цикл `Issue` как самостоятельную внутреннюю рабочую сущность;
- полный жизненный цикл `PR/MR` как отдельную внутреннюю сущность-сироту;
- файловую документацию вне репозиториев проекта как канонический источник истины;
- runtime-чтение flow, ролей и шаблонов промптов напрямую из репозитория при каждом запуске агента;
- бинарные голосовые и графические вложения в PostgreSQL, если для них есть отдельное объектное хранилище с retention-политикой;
- полный текст технических логов в PostgreSQL без отдельного осознанного решения по log storage.

## 11. Что будет уточняться в следующих волнах
- точный словарь типов задач и переходов;
- правила работы с полями провайдера, labels и watermark;
- точная сервисная карта;
- точная модель `job`, очередей и статусов build/deploy;
- точная модель retention и регламентных cleanup job;
- контракт внешних каналов взаимодействия;
- точная модель уведомлений, подписок и уровней серьёзности;
- точная структура установочных фикстур flow, ролей и шаблонов промптов;
- точный формат описания источников проектной документации в `services.yaml`;
- risk/release governance;
- подробная карта frontend-интерфейсов.

## 12. Следствия для последующих волн
- Волна 2 не должна возвращать искусственные рабочие сущности, которые спорят с этой моделью.
- Волна 3 должна проектировать данные и provider integration вокруг `Issue/PR/MR/comments/mentions`, а не вокруг старого label-driven control-plane.
- Волна 3 должна отдельно спроектировать контур platform jobs и его связь с slot/deploy/runtime без записи полного лога в PostgreSQL.
- Волна 5 должна строить интерфейсы вокруг агента-менеджера, задач и процессов, а не вокруг самодостаточного дашборда из внутренних сущностей.
