---
doc_id: REF-CK8S-0008
type: work-model
title: "kodex — нативная для провайдера модель работы с Issue и PR"
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-wave1"
  approved_by: "ai-da-stas"
  approved_at: 2026-04-21
---

# Нативная для провайдера модель работы с `Issue` и `PR`

## TL;DR
- Работа в платформе строится вокруг `Issue`, `PR/MR`, комментариев, mentions и связей между ними.
- Долгоживущий ролевой агент в slot не должен превращать MCP в основной путь создания `Issue/PR`. Для обычной работы с provider-native артефактами он использует `gh` или нативный API провайдера от имени настроенного аккаунта.
- Быстрый agent-manager, наоборот, по умолчанию работает с платформой через платформенный MCP-сервер и через него же инициирует разрешённые платформенные и provider-операции.
- MCP и платформенные инструменты используются для оркестрации, policy, аудита, управления runtime и связи с пользователем, но не подменяют обычный рабочий контур создания `Issue/PR`.
- Обязательные платформенные признаки в `Issue/PR` должны оформляться через читаемый body contract и watermark.
- Acceptance machine обязана проверять полноту оформления. Если обязательных данных не хватает, сессия возобновляется с замечанием, что нужно дополнить.
- Все операции с провайдером проектируются через интерфейсы; GitHub идёт первой реализацией, GitLab и другие провайдеры должны подключаться без перелома доменной модели.
- Provider-native ветки и теги остаются во внешнем провайдере; платформа хранит только release policy, release line и состояние автоматизации вокруг них.

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

Новая модель должна позволять:
- работать из фронтенда;
- работать прямо из GitHub/GitLab;
- одинаково понимать, что происходит, и человеку, и агенту, и машине приёмки.

## 2. Канонические рабочие объекты

### `Issue`
Базовая единица управления работой.

Минимально значимые параметры `Issue`, на которые должна опираться платформа:
- тип задачи;
- labels;
- relationships;
- milestone и project fields, если они реально используются в конкретном провайдере;
- assignees;
- body;
- комментарии;
- mentions;
- состояние открытия/закрытия.

### `PR/MR`
Артефакт изменения.

Минимально значимые параметры `PR/MR`:
- ссылка на исходную задачу;
- состояние review;
- body;
- комментарии;
- labels;
- статус mergeability;
- связанные проверки и evidence.

Одна задача может порождать несколько связанных `PR/MR` в разных репозиториях, если flow, роль и policy проекта это разрешают. Например, один `PR` меняет код сервиса, второй обновляет продуктовую документацию, третий меняет документацию зависимого сервиса.

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

### Комментарий
Может быть:
- уточняющим;
- управляющим;
- review-комментарием;
- запуском агента через mention;
- ответом платформы.

## 3. Разделение `flow`, `stage`, `role` и provider-native артефактов

Чтобы модель не смешивала разные уровни, фиксируется жёсткое разделение:
- `flow` задаёт общий путь выполнения работы;
- `stage` задаёт правила одного этапа;
- профиль роли задаёт, что умеет агент и в каком контуре он может работать;
- `stage role binding` задаёт, как именно эта роль участвует в конкретном этапе;
- provider-native артефакты `Issue/PR/MR/comment` остаются результатом работы, а не заменой этих сущностей.

Из этого следует:
- профиль роли сам по себе не означает, что роль обязана работать на каждом этапе;
- требование создать `PR/MR` или follow-up `Issue` относится к этапу и acceptance profile, а не к профилю роли;
- роль проверки или `gatekeeper` может вообще не создавать новый артефакт, если stage rules требуют только комментарий, approval или структурированный feedback.

## 4. Типы задач

### Канонический принцип
Тип задачи важнее, чем попытка создавать отдельные внутренние рабочие сущности.

### Базовый набор типов
Первый канонический набор типов должен покрывать:
- `initiative`
- `intake`
- `research`
- `vision`
- `prd`
- `arch`
- `design`
- `plan`
- `dev`
- `qa`
- `release`
- `postdeploy`
- `ops`
- `self-improve`
- `review-followup`
- `risk`
- `incident`

Это не окончательный закрытый каталог на все времена, но все новые типы должны появляться только через явное policy-решение, а не ad-hoc.

### Как тип задачи связан с этапом flow
Базовое правило такое:
- этапная задача несёт тип текущего этапа;
- follow-up задача следующего этапа несёт тип следующего этапа;
- служебные и специальные задачи используют отдельные специальные типы.

Пример:
1. агент работает по задаче типа `intake`;
2. на выходе создаёт `PR` с артефактами intake;
3. если flow требует следующий этап, агент создаёт follow-up `Issue` типа `vision`.

Тип `review-followup` не заменяет этапную follow-up задачу. Он нужен только для отдельных follow-up действий, которые возникают из контура проверки и не являются штатным переходом в следующий этап.

## 4.1. Provider-native ветки, release branches и release lines

### Базовый принцип
Ветки, теги и merge-поток остаются provider-native объектами.

Платформа не должна:
- создавать отдельную внутреннюю рабочую сущность ветки;
- хранить собственную истину по состоянию веток вместо провайдера;
- дублировать release branch lifecycle как внутренний каталог веток.

### Что платформа добавляет поверх веток
Платформа добавляет:
- `release policy`;
- `release line`;
- release gates;
- стратегию выкладки;
- связи между релизной веткой, задачами, `PR/MR`, deploy `job` и postdeploy-сигналами.

Такой подход позволяет:
- управлять release trains;
- поддержать canary и поэтапную выкладку;
- не ломать provider-first модель.

## 4.2. Automation rules и trigger-driven создание задач

### Базовый принцип
Автоматический запуск не создаёт отдельный внутренний мир задач.

Канонический путь:
- automation rule хранится в платформе;
- cron или trigger приводит к созданию provider-native `Issue` нужного типа или к запуску flow в допустимом контуре;
- дальше процесс снова работает через обычные `Issue`, `PR/MR`, комментарии, release rules и provider-native связи.

Примеры:
- ночной `ops` или `postdeploy` flow;
- задача на расследование production alert;
- плановый health-check release line;
- регулярная self-improve задача по guidance package.

### Специальные типы задач

#### `research`
Задача исследовательского диалога с агентом по идее, гипотезе или теме, где результатом может быть:
- уточнение;
- решение не продолжать работу;
- запуск нужного flow через создание новой задачи с целевым типом и параметрами.

#### `self-improve`
Задача на анализ и улучшение работы агента или группы агентов.

Она должна ссылаться на исходные артефакты, например:
- исходный `Issue`;
- связанный `PR/MR`;
- запись агентной сессии;
- evidence по ошибке или неудачному результату.

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

В первой версии self-improve не меняет flow, роли и шаблоны промптов напрямую. Такой контур будет добавлен отдельно: агент сможет предложить изменение, но публикация новой версии должна пройти через UI, policy-проверку и аудит. Если задача относится к руководящим правилам, рабочим репозиторием становится репозиторий `guidance package`. Если задача относится к проектной документации, рабочий набор определяется источниками проектной документации в `services.yaml`.

## 5. Что агент оформляет в `Issue/PR`

### Обязательные элементы `Issue`
- понятный заголовок;
- человекочитаемое описание задачи;
- указание рабочего типа;
- ссылка на родительский контекст, если задача follow-up;
- открытая инструкция для следующего исполнителя;
- watermark, который может проверить машина.

### Обязательные элементы `PR/MR`
- понятный заголовок;
- ссылка на исходный `Issue`;
- описание, что сделано;
- проверки и ограничения;
- следующий ожидаемый шаг;
- watermark.

Для результата по нескольким репозиториям каждый `PR/MR` обязан ссылаться на исходную задачу и показывать свою роль в общем наборе изменений. Acceptance machine проверяет не только каждый `PR/MR` отдельно, но и полноту всего ожидаемого набора.

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

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

Такие роли всё равно должны подчиняться общему контракту:
- иметь профиль роли;
- иметь обязательный `work`-шаблон;
- иметь необязательный `revise`-шаблон, если роль должна устранять замечания в собственных артефактах.

При этом профиль роли не задаёт сам по себе:
- на каком именно этапе flow роль запускается;
- обязателен ли её результат для перехода;
- нужно ли от этой роли создание `PR/MR`, approval или только комментарий.

Это определяется `stage role binding` и acceptance profile конкретного этапа.

### Что такое watermark в этой модели
Watermark не должен быть магическим нечитаемым мусором.

Он обязан:
- быть стабильно парсируемым;
- не мешать человеку читать артефакт;
- позволять машине приёмки понять, что контракт заполнен;
- быть совместимым с GitHub/GitLab.

Окончательный формат watermark будет зафиксирован в волне про данные и provider integration.

## 6. Два контура работы с провайдером и платформой

### 5.1. Быстрый платформенный agent-manager
Agent-manager по умолчанию работает через платформенный MCP-сервер.

Через него он:
- получает актуальные данные owner-сервисов;
- запускает flow и role-агентов;
- создаёт запросы апрува и обратной связи;
- вызывает разрешённые platform-owned операции;
- инициирует provider-операции через `provider-hub`, если это нужно для быстрого сценария без запуска slot-агента.

Для agent-manager MCP — это основной рабочий интерфейс к платформе.

### 5.2. Долгоживущий ролевой агент в slot
Ролевой агент в slot работает в смешанном режиме:
- provider-native артефакты оформляет обычным рабочим способом;
- platform-owned операции делает через платформенный MCP-сервер.

Это разделение нужно потому, что slot-агент:
- долго живёт рядом с кодом и окружением;
- должен нормально работать с `Issue/PR/comments` как обычный исполнитель;
- при этом не должен получать прямой доступ к скрытым платформенным внутренностям, секретам и approval-механике.

На этом же контуре допускается, что разные роли работают с одним и тем же набором артефактов по-разному:
- основной исполнитель создаёт `PR` и follow-up `Issue`;
- проверяющая роль комментирует и ставит аппрув;
- контрольная роль проверяет отдельный policy-аспект и тоже оставляет свой результат в `PR` или `Issue`.
- `qa` или мониторинговая роль может дополнительно запускаться в production-контуре только для чтения и по результату оставить комментарий, оформить `PR` с отчётом или создать follow-up `Issue` на дефект, наблюдение или откат релиза.

## 7. Что slot-агент делает через `gh`, а что нет

### 6.1. Через `gh` или API провайдера
Slot-агент создаёт и обновляет:
- `Issue`;
- `PR/MR`;
- комментарии;
- labels;
- relationships;
- assignees;
- milestone и project fields, если они входят в поддерживаемый policy.

Это считается обычным рабочим контуром взаимодействия с GitHub/GitLab.

Если задача разрешает работу с несколькими репозиториями, slot-агент использует тот же provider-native контур для каждого репозитория. Разрешённый набор репозиториев и путей приходит из project policy, `services.yaml`, профиля роли и состава workspace.

Конкретный объём разрешённых операций зависит от профиля роли:
- одни роли имеют право только комментировать и ставить аппрув;
- другие могут создавать follow-up `Issue`;
- третьи дополнительно обновляют `PR/MR` и provider-native поля.

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

### 6.2. Не через `gh`
Через MCP и внутренние платформенные инструменты slot-агент выполняет:
- запуск и остановку runtime;
- запросы апрува;
- аудит действий;
- запись session/run state;
- доставку вопросов пользователю;
- вызов platform-specific tools;
- сервисные операции, которые не должны напрямую жить в GitHub/GitLab.

### 6.3. Опасные операции через MCP
Опасные операции slot-агент должен выполнять не напрямую, а только через MCP-ручки с изоляцией секретов и детерминированным согласованием действий.

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

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

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

### 6.4. Внешние MCP-серверы
Платформа должна поддерживать не только встроенные MCP-инструменты, но и подключаемые внешние MCP-серверы.

Это нужно для сценариев вроде:
- внешних знаний и справки;
- approval/executor контуров;
- интеграций со сторонними системами;
- специальных project-specific tools.

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

## 8. Acceptance machine и обязательная полнота

### Что она проверяет
Acceptance machine должна уметь проверить:
- есть ли обязательный тип задачи;
- хватает ли обязательных sections в body;
- присутствует ли watermark;
- есть ли ссылка на родительский контекст;
- соответствует ли `PR/MR` ожидаемому этапу;
- создан ли follow-up `Issue`, если flow требует следующий этап.

### Что происходит при ошибке
Если артефакт создан, но обязательные данные не заполнены:
1. переход не считается завершённым;
2. в сессию возвращается замечание, что именно не заполнено;
3. ролевой агент получает задачу дополнить body или связи;
4. только после успешной перепроверки возможен следующий шаг.

Таким образом, машина не подчищает за агентом молча, а заставляет завершить оформление до конца.

## 9. Минимум платформенного шума
Новая модель запрещает перегружать `Issue/PR` лишними платформенными сущностями и дублирующими полями.

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

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

## 10. Лейблы, поля и связи

### Что сохраняется
Labels остаются допустимым механизмом семантики и запуска, но перестают быть единственным центром модели.

Платформа должна уметь опираться на комбинацию:
- type;
- labels;
- relationships;
- comments/mentions;
- milestone/project fields;
- watermark/body contract.

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

## 11. Что это значит для GitHub и GitLab
Модель сразу проектируется с приоритетом провайдера:
- GitHub идёт первым;
- GitLab проектируется через те же интерфейсы и провайдерные адаптеры;
- платформа не должна завязываться на уникальные GitHub-трюки, если их нельзя разумно выразить в GitLab-подобной модели.

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

Если какое-то поле есть только в одном провайдере, оно может использоваться как дозаполняемый контекст, но не как неснимаемая основа всей модели.

## 12. Что будет спроектировано в следующей волне
- точная модель данных для зеркальных проекций, состояния дозаполнения и платформенных метаданных;
- точный watermark format;
- матрица полей провайдера и обязательности;
- правила синхронизации между GitHub/GitLab и внутренним состоянием платформы;
- правила mentions, лимитов провайдера и account selection.

Минимальная модель синхронизации уже считается принятой:
- webhook сначала сохраняется в `provider_event_inbox`, а проекции пересчитываются асинхронно и идемпотентно;
- для каждой области синхронизации провайдера хранится `sync_cursor` и окно перекрытия, чтобы incremental reconciliation находил изменения при потерянном webhook;
- активные flow, открытые `PR/MR`, Human gate, release line, running `run` и ожидаемая приёмка считаются горячими сущностями и проверяются чаще;
- закрытые и архивные сущности не должны постоянно расходовать лимиты провайдера;
- если slot-агент изменил артефакт через `gh`, он передаёт идентификатор провайдера платформе как ускоряющий сигнал на обновление, но источником истины остаётся провайдер.

Для учёта лимитов прямой `gh`-работы принято:
- `gh api rate_limit` используется как снимок лимитов до и после agent-run;
- `gh api --include` может передавать платформе заголовки ответа для операций, выполненных через `gh api`;
- обычные команды `gh issue` и `gh pr` не считаются достаточным источником полной телеметрии лимитов;
- строгий учёт и принудительное соблюдение лимитного бюджета требуют будущего provider proxy или MCP-ручек платформы.
