---
doc_id: REF-CK8S-0013
type: acceptance-contract
title: "kodex — контракт артефактов, watermark и приёмка в третьей волне"
status: active
owner_role: EM
created_at: 2026-04-21
updated_at: 2026-04-22
related_issues: [376, 470, 488]
related_prs: []
approvals:
  required: ["Owner"]
  status: approved
  request_id: "owner-2026-04-21-refactoring-wave3"
  approved_by: "ai-da-stas"
  approved_at: 2026-04-21
---

# Контракт артефактов, watermark и приёмка в третьей волне

## TL;DR
- Агентные `Issue/PR` должны оставаться читаемыми для человека и одновременно машинно-проверяемыми.
- Для этого у каждого структурированного артефакта есть две части: открытая инструкция для человека и компактный watermark для машины.
- Watermark фиксируется в едином Markdown-совместимом формате, который работает и в GitHub, и в GitLab.
- Acceptance machine проверяет не "вообще похоже ли на нормальный текст", а конкретный контракт разделов, provider-native полей, связей и watermark.
- Если артефакт недооформлен, переход не завершается: сессия возобновляется с замечанием, что именно надо дополнить.

## 1. Зачем нужен двойной контракт
Новая модель не должна скатываться ни в один из двух дефектов:
- чисто человеческий текст, который машина не может надёжно проверить;
- чисто технический watermark, который превращает `Issue/PR` в непонятный служебный контейнер.

Поэтому канонический артефакт состоит из:
1. открытых человекочитаемых разделов;
2. компактного машинного watermark-блока.

## 2. Какие артефакты подпадают под контракт

### 2.1. Обязательные
Контракт обязателен для:
- `Issue` типа `initiative`;
- этапных задач;
- follow-up задач;
- агентно-сгенерированных `PR/MR`;
- структурированных агентных комментариев, которые платформа должна потом перечитать и проверить.

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

### 2.2. Необязательные
Контракт не обязателен для:
- обычных человеческих комментариев;
- review-комментариев человека;
- коротких служебных ответов, которые не являются новым рабочим артефактом.

## 3. Открытая инструкция

### 3.1. Канонический смысл
Открытая инструкция — это человекочитаемая часть артефакта, в которой прямо сказано:
- зачем создан артефакт;
- что нужно сделать дальше;
- какой следующий ожидаемый результат;
- какие ограничения и проверки важны;
- какие артефакты уже связаны с текущим шагом.

### 3.2. Базовые разделы для `Issue`
Минимальный канонический набор разделов для структурированного `Issue`:
- `## Контекст`
- `## Что требуется сделать`
- `## Следующий ожидаемый результат`
- `## Ограничения и проверки`
- `## Связанные артефакты`

Если task-type требует более детального шаблона, flow/prompt policy может добавить разделы, но не убрать этот базовый минимум.

### 3.3. Базовые разделы для `PR/MR`
Минимальный канонический набор разделов:
- `## Что сделано`
- `## Что проверить`
- `## Ограничения и риски`
- `## Следующий шаг`
- `## Связанные артефакты`

### 3.4. Базовые разделы для структурированного агентного комментария
Минимальный канонический набор:
- `## Смысл сообщения`
- `## Что требуется от человека или платформы`
- `## Следующее действие`

Если комментарий является только промежуточным диагностическим сообщением без продолжения процесса, этот контракт применять не нужно.

## 4. Watermark как машинный блок

### 4.1. Общий формат
Watermark фиксируется в Markdown-совместимом HTML-комментарии:

```md
<!-- kodex:artifact v1
kind: issue
work_type: vision
flow: full-delivery
stage: vision
source_ref: issue#123
parent_ref: issue#120
next_ref: issue:prd
managed_by: kodex
-->
```

Это канонический формат для wave 3.

### 4.2. Почему выбран именно такой формат
Он:
- не ломает рендеринг GitHub/GitLab;
- не мешает человеку читать основной текст;
- легко парсится;
- устойчив к ручному редактированию;
- не требует добавлять во внешний артефакт внутренние служебные id платформы.

### 4.3. Что запрещено в watermark
Нельзя включать туда:
- секреты;
- чувствительные токены;
- полные внутренние payload;
- быстро устаревающее runtime-состояние;
- внутренние технические идентификаторы, если без них можно обойтись.

## 5. Минимальные поля watermark

### 5.1. Обязательные поля для всех структурированных артефактов
- `kind`
- `managed_by`

### 5.2. Обязательные поля для `Issue`
- `work_type`
- `source_ref`, если задача порождена из другой задачи или этапа
- `parent_ref`, если это follow-up

### 5.3. Обязательные поля для `PR/MR`
- `work_type`
- `source_ref`

### 5.4. Поля по policy
В зависимости от flow допускается требовать:
- `flow`
- `stage`
- `next_ref`

Но эти поля не должны превращаться в шум ради шума. Их добавляют только там, где acceptance machine и следующий исполнитель реально ими пользуются.

## 6. Где проходит граница между provider-native полями и watermark

### 6.1. Что должно жить в provider-native полях
Если смысл хорошо выражается нативно, используем:
- type;
- labels;
- relationships;
- milestone;
- project fields;
- assignees;
- ссылку `PR` на исходный `Issue`.

### 6.2. Что должно жить в watermark и открытой инструкции
В watermark и разделы выносим:
- flow-контекст;
- машиночитаемую связь шага с ожидаемым следующим результатом;
- открытое описание того, что делать дальше;
- platform-specific контекст, который некуда положить нативно без искажения смысла.

### 6.3. Что нельзя делать
Нельзя:
- дублировать один и тот же смысл во всех возможных полях одновременно;
- переносить быстро меняющийся внутренний статус платформы в labels/body только ради удобства машины;
- заставлять человека читать технический шум вместо понятной задачи.

## 7. Acceptance machine

### 7.1. Что она проверяет
Acceptance machine должна проверять:
- соответствует ли provider-native тип ожидаемому work-type;
- присутствуют ли обязательные разделы;
- присутствует ли корректный watermark;
- есть ли нужные provider-native связи;
- создан ли ожидаемый follow-up артефакт, если этого требует flow;
- создан ли полный набор `PR/MR` по нескольким репозиториям, если этого требует задача, состав источников проектной документации или flow;
- не нарушены ли policy и risk-gates перед переходом дальше.

### 7.2. Что она не делает
Acceptance machine не должна:
- сама молча чинить артефакт;
- придумывать за агента недостающий смысл;
- заменять review человека;
- принимать release/governance-решения вместо нужного gate.

## 8. Что происходит при провале приёмки

### 8.1. Базовый сценарий
Если проверка не пройдена:
1. переход не завершается;
2. `agent-manager` фиксирует конкретный список недостающих элементов;
3. текущая сессия возобновляется или создаётся корректирующее продолжение;
4. агент обязан дописать body, связи или provider-native поля;
5. acceptance machine выполняет повторную проверку.

### 8.2. Как формулируется замечание
Замечание должно быть структурированным и конкретным.

Примеры допустимых замечаний:
- отсутствует раздел `## Следующий ожидаемый результат`;
- у `PR` нет корректной ссылки на исходный `Issue`;
- watermark не содержит `work_type`;
- flow требует follow-up задачу следующего этапа, но она не создана;
- provider-native type не совпадает с ожидаемым типом текущего шага.

### 8.3. Когда acceptance должна эскалировать человеку
Если агент:
- повторно не может выполнить контракт;
- упёрся в внешние ограничения;
- не может выставить обязательные provider-native поля;
- столкнулся с противоречием policy,

тогда acceptance machine должна не бесконечно гонять исправления, а переводить процесс в состояние ожидания и инициировать запрос к человеку.

### 8.4. Когда acceptance запускает дополнительные роли
Acceptance profile может требовать не прямого перехода к следующему этапу, а запуска дополнительных ролей проверки и контрольных ролей на уже созданных артефактах.

Допустимый канонический сценарий:
1. основной агент завершает этап и оформляет `PR` и follow-up `Issue`;
2. acceptance machine подтверждает базовый контракт артефактов;
3. `agent-manager` запускает одну или несколько дополнительных ролей;
4. эти роли работают с тем же `PR` и follow-up `Issue`, оставляют комментарии, замечания или approval;
5. только после этого этап либо считается полностью принятым, либо уходит в корректирующий цикл.

Выбор этих дополнительных ролей задаётся не профилем роли сам по себе, а `stage role binding` и acceptance profile конкретного этапа.

Пример такого сценария:
- роль `vision-reviewer` проверяет `PR` с документацией vision и связанный follow-up `Issue` следующего этапа;
- роль `lexical-gatekeeper` проверяет, что в документации и теле follow-up `Issue` нет избыточной смеси русского и английского;
- роль `qa` или мониторинга после релиза может работать в production-контуре только для чтения, публиковать структурированный комментарий под release-задачей, открывать follow-up `Issue` на дефект или откат и, если нужно, оформлять `PR/MR` с отчётом и документацией по результатам проверки;
- все такие роли используют свои профили, права доступа, шаблоны промптов и режим исполнения, но работают поверх тех же provider-native артефактов.

## 9. Как этот контракт влияет на prompts и реализацию

### 9.1. Что обязаны делать prompts
Prompt blocks для ролей и flow обязаны:
- требовать открытые разделы;
- требовать watermark;
- объяснять, какие provider-native поля нужно заполнить;
- учитывать, что у роли есть `work`-шаблон и необязательный `revise`-шаблон;
- учитывать, что flow и шаблоны промптов выбраны из утверждённых версий в БД;
- объяснять агенту состав workspace: где код, где проектная документация и где руководящие пакеты;
- различать основной этапный запуск и дополнительный запуск роли проверки или контроля, если flow этого требует;
- не разрешать завершать шаг без полного оформления артефакта.

### 9.2. Что обязана делать реализация
Реализация должна:
- уметь парсить watermark детерминированно;
- проверять контракт разделов;
- сверять body contract с provider-native state;
- возвращать агенту конкретные поправки, а не абстрактное "не прошло".

## 10. Что intentionally не фиксируется в этой волне
В этой волне не фиксируются:
- точные тексты шаблонов промптов и полный каталог встроенных и пользовательских ролей;
- все специализированные stage-варианты разделов;
- финальный UI acceptance inspector;
- механизм публикации обучающих комментариев.

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