# Задание A28: субагенты и реестр ролей

## Дата поступления
2026-08-25

## База
Проверочный HEAD на момент выдачи: **`d5429da`**.

## Ветка
`antigravity/subagents-role-registry`

## Порядок исполнения

Два прохода: **Flash** реализует, **Pro** проводит аудит. Пункт **P0-5** написан для аудитора.

Это **первое** из трёх заданий по новому фронтенду (A28, A29, A30) и **основа для остальных**: главный экран рисует агентов, поэтому агенты должны появиться раньше экрана. A29 и A30 опираются на реестр ролей отсюда.

---

## Порядок работы с git

```
cd <каталог репозитория>; git fetch origin --prune; git status
git checkout main; git pull --ff-only origin main
git checkout -b antigravity/subagents-role-registry
git commit -m "..."          <- сначала коммит
git push -u origin antigravity/subagents-role-registry
```

В `main` напрямую не пушить. В конце — push, `git log --oneline -1`, `git status` чистый.

---

## Задача

Сейчас в системе **шесть** ролей. Владелец хочет двенадцать — полноценную команду субагентов с внятно расписанными обязанностями. Список и формулировки даны им дословно и приведены ниже; **менять их смысл нельзя**.

---

## Что проверено исполнением — заново не выясняйте

**1. Новая роль добавляется через конфигурацию и доходит до снапшота.**

```
ролей в умолчаниях: 6 -> orchestrator, coder-primary, coder-secondary, reviewer, research, fast
после добавления роли tester в router_profiles.yaml: True
видна ли в снапшоте: True
```

Архитектуру ломать не нужно: `config.roles` уже произвольный словарь.

**2. Но подпись падает в сырой идентификатор.** У добавленной роли `role_name_ru` оказался `tester`, а не человеческое имя, потому что таблица подписей зашита в код:

```
unified_health.py:775   ROLE_NAMES = {...}          семь записей
auto_assigner.py:28     HUMAN_ROLE_LABELS = {...}   одиннадцать записей
```

**3. Список ролей зашит ещё в двух местах:**

```
auto_assigner.py:371     canonical_roles = ["orchestrator", "coder-primary", ...]
telemetry_service.py:402 roles = set(known_roles or ["orchestrator", ...])
```

Пока эти списки литеральные, новые роли будут выпадать из авто-распределения и из аналитики.

**4. Понятия «субагент» как сущности нет.** `universal_subagent` в `auto_assigner` — это подпись слота, а не отдельный агент. Файлов агентов (`agents/*.md`) в проекте нет вовсе.

---

## P0-1. Реестр ролей вместо литералов

Завести **один** источник истины для ролей: идентификатор, человеческое имя, описание обязанностей, порядок отображения.

Все четыре места выше должны читать оттуда. Литеральных списков ролей в коде остаться не должно — проверяется поиском.

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

## P0-2. Двенадцать ролей и их обязанности

Формулировки владельца. Описание каждой роли обязано быть **видно в интерфейсе** — на карточке агента и в инспекторе, а не только в конфигурации.

| Идентификатор | Имя | Обязанности |
|---|---|---|
| `researcher` | Исследователь | Изучает данные, кодовую базу, документацию и внешние источники, чтобы собрать информацию для решения задачи. |
| `developer-1` | Разработчик 1 | Пишет код, реализует функционал, исправляет ошибки. |
| `developer-2` | Разработчик 2 | Проверяет код Разработчика 1 и выдаёт ему задание на исправление. |
| `code-reviewer` | Код-ревьювер | Анализирует код на ошибки, проблемы безопасности и соответствие стандартам. Работает **после** Разработчика 2. |
| `tester` | Тестировщик | Создаёт тесты, проверяет корректность работы кода, находит дефекты. |
| `tech-writer` | Технический писатель | Создаёт документацию, инструкции, README. |
| `analyst` | Аналитик | Проводит глубокий анализ данных, выявляет тренды, строит прогнозы. |
| `guardian` | Надзиратель (агент безопасности) | Проверяет входящие инструкции на промпт-инъекции, анализирует планы и вызовы инструментов, блокирует обход системных правил, не допускает утечки секретов, следит за границами песочницы. |
| `cost-controller` | Агент контроля затрат | Оценивает планируемый расход токенов, сравнивает с остатком бюджета, предлагает упрощения, сверяет факт с прогнозом, останавливает цепочку при исчерпании лимита. |
| `manager` | Менеджер (планировщик) | Определяет стратегию, распределяет ресурсы, контролирует ход выполнения. |
| `integration-expert` | Специалист по интеграции | Работает с API и внешними сервисами, отправляет вебхуки. |
| `security-expert` | Юрист / специалист по безопасности | Проверяет код и данные на уязвимости. |

Порядок в таблице — порядок отображения.

**Существующие шесть ролей не удалять и не переименовывать молча.** У владельца в конфигурации на трёх машинах живут `orchestrator`, `coder-primary`, `coder-secondary`, `reviewer`, `research`, `fast`, и на них ссылаются цепочки. Предложите соответствие старых новым (например `research` → `researcher`, `coder-primary` → `developer-1`) и **проведите миграцию**, сохранив цепочки. Соответствие описать в отчёте; спорные случаи вынести владельцу, а не решать молча.

## P0-3. Надзиратель и контроль затрат — особый случай

Эти двое отличаются от остальных: они не выполняют задачу пользователя, а **проверяют** работу других.

Задание **не требует** реализовывать их поведение — это отдельная работа. Требуется:

1. Завести их как роли наравне с прочими, с полным описанием обязанностей в интерфейсе.
2. **Честно показать, что исполнение ещё не реализовано.** Не рисовать зелёный статус «Работает» у агента, который ничего не делает. Состояние «Роль объявлена, исполнение не реализовано» — допустимо и честно; выдуманная активность — нет.

Правило проекта без исключений: ни одного статуса, числа или метрики без основания.

## P0-4. Двенадцать ролей и квоты

Двенадцать агентов на нескольких аккаунтах — это про распределение нагрузки, и здесь легко всё сломать.

- Один аккаунт по-прежнему может обслуживать несколько ролей (проверено в A26, движок это держит).
- Авто-распределение из A26 обязано работать и на двенадцати ролях: при одном провайдере он встаёт во все двенадцать, при нескольких — по назначению.
- Пороги квот из A26 не должны деградировать.

Прогоните авто-распределение на двенадцати ролях и приложите вывод.

## P0-5. Аудит вторым проходом

1. **Литеральные списки ролей.** Пройдите поиском по `orchestrator`, `coder-primary`, `reviewer` и убедитесь, что нигде не осталось зашитого перечня. Именно из-за таких списков добавленная роль показывалась как `tester`.
2. **Выдуманные статусы.** Особый риск в P0-3: у нереализованных ролей не должно быть активности, метрик и зелёных индикаторов.
3. **Миграция конфигурации владельца.** Проверьте на копии его `router_profiles.yaml`, что цепочки уцелели и маршрутизация работает. Конфигурацию литералами не править.
4. **Запустить изменённое**, а не только импортировать.
5. **Побочные изменения** объяснить.
6. **Пропущенный пункт назвать пропущенным.**

---

## Ограничения

- Десктоп (`router/ui/**`) не трогать.
- Ваша зона: `auto_assigner.py`, `unified_health.py`, `telemetry_service.py`, `router_config.py`, конфигурации, соответствующие тесты и минимальные правки веб-клиента для показа описаний.
- Граф workflow и связи между агентами — **не здесь**, это A30. Не начинайте.
- Дизайн-система и темы — **не здесь**, это A29.
- Правило честности без исключений.
- Тег `v0.1.1` не создавать.

## Критерии приёмки

1. Ветка в `origin`, `git status` чист.
2. Двенадцать ролей заведены, у каждой человеческое имя и описание обязанностей; описание видно в интерфейсе.
3. Литеральных списков ролей в коде не осталось; проверено поиском, результат в отчёте.
4. Добавление роли в конфигурацию даёт человеческую подпись всюду; проверено на роли, которой нет в реестре по умолчанию.
5. Существующие шесть ролей мигрированы, цепочки владельца уцелели; проверено на копии его конфигурации.
6. Авто-распределение отработало на двенадцати ролях; вывод приложен.
7. У ролей без реализации исполнения нет выдуманной активности и метрик.
8. `ruff check .` чисто; релизный гейт не ухудшен.
9. Отчёт: `START_HEAD`, `FINAL_HEAD`, `origin/main`, `git status`, `X passed / Y skipped / Z failed`. На `main` сейчас **450 passed, 2 skipped**.

## Главное

Двенадцать субагентов с внятными обязанностями — основа нового главного экрана. Пока роли зашиты литералами, ни новый экран, ни маршрутизация из A29 нормально не заработают.

## Порядок сдачи
Передать точный `FINAL_COMMIT_SHA`. Сдано только после появления коммита в `origin`.
