Артефакты

Реестр документов с согласованием людьми — регламенты, требования и инструкции, которым агенты доверяют.

Артефакт — документ в реестре: регламент кодирования, требования к фиче, инструкция по выкладке, шаблон сметы, чек-лист аудита. В промпт агента попадает только ссылка; тело агент подгружает по требованию (artifact_search / artifact_read с аудитом чтения). Так большой регламент не съедает контекст, но всегда доступен, когда нужен.

Главная ценность — доверие. У артефакта есть статус, версия и круг согласования, поэтому «смотри регламент X» означает проверенный людьми документ, а не случайный черновик: агент предлагает, человек утверждает.

Страница Артефакты (/artifacts), детали — docs/artifact-registry.md и docs/artifact-lifecycle.md.

#Типы и назначение

Назначение (kind) делит один реестр на два сценария потребления:

• reference — регламенты, инструкции, чек-листы: то, на что ссылаются навыки;
• work — требования, спеки, проектные решения: рабочие продукты, которые производятся и согласуются в задачах и сагах.

Реализованное требование может позже стать reference-документом нового навыка — той же записью с другим kind после нового круга согласования.

#Статусы и версии

Жизненный цикл ведётся на уровне версии:

Правка утверждённого — всегда новая версия и новый круг согласования. Утверждённая версия продолжает обслуживать агентов и навыки, пока редакция проходит согласование. Навыки ссылаются на id артефакта и всегда резолвятся в последнюю утверждённую версию.

#Согласование

• Только человек утверждает. Само-одобрение запрещено на уровне API: решение принимает именованный человек, а не агент и не «сумма сигналов».
• Круг согласования. Автор отправляет артефакт на ревью (идемпотентно по версии, квота ARTIFACT_SUBMIT_PER_DAY на ран — защита очереди от зафлудившего рана) и назначает согласующих: конкретный человек, подразделение, роль или владелец проекта. Подразделение раскрывается в активных людей на момент отправки; голова подразделения тоже согласующий.
• Режимы. all — решение принято, когда все ответили «за» (первое «против» закрывает круг отказом); any — достаточно первого ответа.
• Решение из мессенджера. Каждый согласующий получает уведомление в свой канал со ссылкой на карточку артефакта и может решить прямо в чате: первое слово ответа решает (approve/одобрить/lgtm — за, reject/отклонить — против), остальное становится комментарием. Неоднозначный ответ круг не закрывает — бот просит ответить по форме.
• Доработка в цикле. Отклонение возвращает артефакт автору с причиной: человек правит сам (в интерфейсе) или агент вносит правки (artifact_update) и отправляет снова. Круги не ограничены, каждый оставляет след в истории согласований.
• Напоминания и эскалация. Круг молчит дольше ARTIFACT_REVIEW_TIMEOUT (по умолчанию 72 часа) — согласующим уходит одно напоминание; ещё через один таймаут — эскалация руководителю отдела артефакта (или администратору). Свип выключается значением 0.
• Идемпотентность. Повторный approve/reject того же круга — 409 без изменения состояния; решение фиксируется ровно один раз. Автор запроса всегда может решить свой собственный круг.

#Инбокс согласований

На странице «Артефакты» первым открывается вкладка My approvals — очередь открытых кругов, адресованных вам: очередь ведёт, каталог — поверхность для поиска. Пока есть что решать, в меню «Артефакты» горит бейдж со счётчиком. Фильтры каталога — статус, возраст, теги, автор (человек или подразделение в одном поле); ссылка вида ?id=… открывает конкретный артефакт.

#Пример: сложно согласованный документ

Как агенты и люди вместе собирают документ, который проходит несколько кругов согласования (по реальному сценарию — требования к доработке):

1. Задача. Пользователь просит в чате: «Соберите требования к доработке панели трассировки и согласуйте с командой». Агент регистрирует сагу (saga_register), которая свяжет всю историю: требования → согласование → раны реализации.
2. Черновик. Агент-аналитик создаёт артефакт kind=work (artifact_create, с saga_id) и наполняет его итерациями. Другие агенты читают черновик в своих ранах (artifact_read честно показывает draft) и дополняют его замечаниями — переиспользование работает до утверждения, но черновик всегда помечен как неподтверждённый.
3. Первый круг. Агент отправляет документ на согласование (artifact_submit): согласующие — org:backend и role:security, режим all, в примечании — контекст и что проверять. Согласующие получают уведомления в мессенджеры.
4. Отказ с содержанием. Security-ревьюер отвечает в треде reject не хватает раздела о секретах — круг закрывается отказом, документ возвращается автору с причиной.
5. Доработка. Агент вносит правки (artifact_update) и отправляет снова — новый круг, оба круга видны в истории согласований с вердиктами и комментариями.
6. Утверждение. Все согласующие отвечают «approve» — версия 1 становится approved и неизменной.
7. Работа на документе. Навык «Реализация фичи» получает ссылку на артефакт (таб Artifacts в редакторе навыка или artifact_refs в skill_propose); агенты-исполнители читают утверждённую версию по требованию — каждое чтение журналируется, так что видно, кто и в каком ране опирался на документ.
8. Новая редакция. Требования меняются: правка утверждённого возможна только новой редакцией (artifact_update с new_version: true) — черновик версии 2 живёт рядом с утверждённой версией 1, повторное согласование проматывает его в approved, а версия 1 становится superseded. Агенты без пауз продолжают работать на живой версии.

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

#Связи

• Сага — артефакт может принадлежать длительной работе (требования к фиче в рамках саги): связка даёт сквозную трассировку от требования до ранов реализации.
• Навык — манифест навыка ссылается на артефакты как на справочные материалы; в навыки попадают только утверждённые.
• Проект / отдел / организация — область видимости: общекорпоративный регламент виден везде, проектный — только в проекте.

#Инструменты агента

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