sdlc-hub/openspec/changes/issue-card-modal/specs/mcp/spec.md

MODIFIED Requirements

Requirement: Инструменты

Инструмент	Параметры	Результат
issues	фильтры как у GET /issues, limit (по умолчанию 50)	таблица: ключ, тема (до 80 символов), статус, срок, исполнитель, спринт, статус по факту
issue	key	поля, связи (обе стороны, с типом и направлением), заметки, последние команды, комментарии: «комментарии (N):» и 5 последних (автор, время, текст до 300 символов с «…»), «ещё M», если их больше 5; без комментариев — «комментариев нет»
notes_set	key, подмножество полей заметок	обновлённые заметки
batch_create	title, commands (список объектов по контракту commands)	id, estimate_seconds, число команд; 422 — текст ошибки валидации
batch_status	id	статусы команд, ошибки, оценка остатка
batch_wait	id, timeout_minutes (≤ 60)	как batch_status, возвращается по завершении или по таймауту
batches	limit	последние пакеты со статусом
command_retry	id	новый пакет
batch_cancel	id	вид пакета; для команд пакета, уже взятых агентом, — строка «команда #N уже у агента и будет выполнена; остановить — POST /commands/N/cancel с force: true»
refresh	keys или full, wait (bool)	без wait — строка с id поставленного пакета; с wait — итог пакета, как у batch_wait
agent_status	—	онлайн/офлайн, версия, текущая команда, довыданные команды (id, тип, число выдач), 429 за сутки, версия настроек; публикация агента («публикация: v от <дата>» или «публикации нет»), состояние обновления («обновление: v → v»), запускатель («запускатель: v», «без запускателя» или, пока agent_reported = false, «запускатель: неизвестно (агент ещё не выходил на связь после перезапуска хаба)»), update_hint, если он есть
sync_log	limit	последние sync_run
settings_get, settings_set	ключ, значение	текущее значение / новая settings_version

Описание инструмента batch_create SHALL предупреждать, что ensure_issue должна нести labels с базовой меткой проекта (AWPCA): хаб и агент метки сами не добавляют, и задача без неё выпадает из базовой JQL и из зеркала.

Автор команд из MCP SHALL быть claude; из API без автора — api.

Scenario: Пакет из чата

• WHEN batch_create {title: "1538 в спринт 2", commands: [ensure_fields{…}, ensure_link{…}, ensure_sprint{…}]}
• THEN пакет создан с четырьмя командами (три + refresh), ответ содержит оценку в минутах

Scenario: Ожидание результата

• WHEN batch_wait {id, timeout_minutes: 10} и пакет завершился через 6 минут
• THEN ответ через 6 минут со статусами всех команд

Scenario: Статус агента с довыдачей

• WHEN агент на связи, команда 40 выдана дважды и ещё без отчёта
• THEN ответ agent_status содержит «агент онлайн» и строку о команде 40 с числом выдач 2

Scenario: Отмена пакета с командой у агента

• WHEN batch_cancel {id: 9}, команда 30 пакета в claimed
• THEN ответ содержит вид пакета и строку «команда #30 уже у агента и будет выполнена; остановить — …»

Scenario: Статус агента после отката

• WHEN опубликована v7, агент v6 под запускателем v1 прислал update_state = rolled_back для v7
• THEN ответ agent_status содержит «публикация: v7 от …», «обновление: rolled_back v6 → v7», «запускатель: v1» и «откат с v7 на v6: …»

Scenario: Статус агента сразу после перезапуска хаба

• WHEN хаб перезапущен, агент ещё не прислал claim
• THEN ответ agent_status содержит «запускатель: неизвестно (агент ещё не выходил на связь после перезапуска хаба)» и не содержит «без запускателя» и «агент запущен без run.py»

Scenario: Задача с семью комментариями

• WHEN issue {key: "AURORA-9001"}, у задачи 7 комментариев, у самого нового текст 500 символов
• THEN ответ содержит «комментарии (7):», 5 последних комментариев (самый новый — первым, обрезан до 300 символов с «…») и «ещё 2»