sdlc-hub/openspec/specs/commands/spec.md

commands Specification

Purpose

TBD - created by archiving change bridge-core. Update Purpose after archive.

Requirements

Requirement: Команда — желаемый результат на одной задаче

Каждая команда SHALL описывать желаемое состояние одной задачи Jira и выполняться агентом как «прочитать → сравнить → записать только разницу». Повторное выполнение любой команды с тем же результатом в Jira SHALL завершаться done без записи. Типы команд и их контракт:

Тип	Параметры	Что читает	Что пишет
ensure_issue	temp_key (new:<n>), issue_type (task/epic), summary, description, priority, duedate, planned_start, planned_end, labels, epic_key, assignee	поиск project = <proj> AND reporter = currentUser() AND created >= -7d, точное сравнение summary	при отсутствии — POST /issue (для эпика — с epic_name_field_id); результат key
ensure_fields	key, любое подмножество: summary, description, priority, duedate, planned_start, planned_end, labels_add, labels_remove, epic_key, assignee	GET /issue/{key}	PUT /issue/{key} только с отличающимися полями; эпик — по epic_link.mode
ensure_comment	key, marker, body	GET /issue/{key}/comment	комментарий с marker в начале: PUT если текст отличается, POST если нет
ensure_status	key, target (имя статуса или список-путь)	GET /issue/{key} (статус), GET /issue/{key}/transitions на каждом шаге	POST /transitions по шагам пути; при отсутствии перехода — failed с перечнем доступных
ensure_link	source, target, link_type (логическое имя из link_types), replace (bool)	GET /issue/{source} (issuelinks)	нет нужной и нет конфликта — POST /issueLink; конфликт (другой тип из link_types или обратное направление) и replace — DELETE лишней, затем POST; конфликт без replace — failed с описанием
ensure_sprint	key, sprint (имя или backlog)	GET /issue/{key} (поле спринта), список спринтов доски из board_id (активные и будущие)	POST /rest/agile/1.0/sprint/{id}/issue или POST /rest/agile/1.0/backlog/issue
refresh	keys (список) или jql	search с полями зеркала, по 100 на страницу; плюс дочитывание соседей по issuelinks	ничего в Jira; состояние уходит в хаб

Семантика ensure_link: source блокирует/ссылается на target; агент в POST /issueLink SHALL ставить source в inwardIssue, target в outwardIssue (проверено на Jira банка 11.10.2026).

Scenario: Повтор уже выполненной команды

• WHEN ensure_fields {key: AURORA-1533, duedate: 2026-10-23} выполняется, а в Jira срок уже 23.10
• THEN агент не делает PUT, отчёт done, jira_calls = 1

Scenario: Замена связи

• WHEN ensure_link {source: AURORA-1537, target: AURORA-1538, link_type: "связанные", replace: true} и в Jira между ними «блокирует начало» 1537→1538
• THEN DELETE старой связи, пауза по политике, POST новой; отчёт done с обеими операциями

Scenario: Связь-конфликт без replace

• WHEN та же команда с replace: false
• THEN failed, в error найденная связь, Jira не изменена

Scenario: Переход по пути

• WHEN ensure_status {key: X, target: ["Разработка", "Готово"]} и X в «Ожидание разработки»
• THEN два POST /transitions с паузой между ними; если X уже «Готово» — done без записи

Scenario: Создание с проверкой дубля

• WHEN ensure_issue повторяется после падения агента, а задача с той же темой от нас уже создана час назад
• THEN агент не создаёт вторую, отчёт done с ключом найденной

Requirement: Временные ключи и ссылки внутри пакета

Параметр-ключ любой команды MAY быть временным new:<n>. Хаб SHALL выдавать агенту такую команду только после done команды ensure_issue с тем же temp_key в том же пакете, подставив настоящий ключ. Если ensure_issue завершилась failed или cancelled, зависимые команды SHALL получить skipped. Временный ключ вне пакета с его ensure_issue SHALL отвергаться при создании пакета (422).

Scenario: Создать и привязать

• WHEN пакет: ensure_issue {temp_key: new:60, …}, ensure_link {source: new:60, target: AURORA-1537, …}
• THEN вторая команда выдаётся агенту с source = AURORA-1590 после завершения первой

Requirement: Пакет и порядок выполнения

Пакет SHALL создаваться одним вызовом с автором, заголовком и списком команд; хаб SHALL назначить seq по порядку списка и добавить в хвост refresh по всем ключам пакета (кроме пакетов, состоящих только из refresh). Очередь SHALL выдавать команды в порядке (batch.created_at, seq), одну в полёте. Пакет и его queued команды MAY быть отменены; claimed команда MUST NOT отменяться автоматически.

Scenario: Оценка длительности

• WHEN создаётся пакет из 3 ensure_fields и 2 ensure_comment
• THEN estimate_seconds = сумма пауз по политике для последовательности типов + пауза refresh

Requirement: Политика темпа и пауза на команде

Хаб SHALL хранить pacing как минимальные зазоры в секундах по типу команды (по умолчанию: ensure_issue и ensure_fields 120, ensure_comment, ensure_status, ensure_link, ensure_sprint 30, refresh 2). При выдаче команды хаб SHALL сообщить pause_seconds = зазор по типу выдаваемой команды; агент SHALL выдержать его от времени своего последнего вызова Jira. Внутри одной команды с несколькими записями (ensure_link с replace, путь переходов) агент SHALL выдерживать зазор типа команды между записями.

Scenario: Нет следующей команды — нет паузы

• WHEN очередь пуста
• THEN claim возвращает пустой ответ, агент не спит сверх долгого запроса

Requirement: Ошибки и подтверждение по состоянию

Ошибка команды SHALL записываться в error (HTTP-код, текст Jira до 1500 символов), пакет продолжается. Команда в claimed без ответа SHALL показываться как «нет ответа от агента с <claimed_at>». Если после любого refresh желаемый результат такой команды виден в зеркале (для ensure_issue — задача с той же темой от нас; ensure_fields — все поля совпадают; ensure_status — статус равен последнему в пути; ensure_link — связь есть и конфликтов нет; ensure_sprint — спринт совпадает), хаб SHALL перевести её в confirmed_by_state. Для ensure_comment и refresh подтверждения по состоянию нет: комментарии в зеркале не хранятся, такая команда ждёт отчёта агента или отмены человеком. Автоматических повторов хаб MUST NOT делать; повтор — новая команда с теми же параметрами по запросу интерфейса.

Scenario: Отчёт потерян, факт на месте

• WHEN ensure_sprint {key: X, sprint: "Спринт 2"} в claimed 20 минут, агент перезапущен, refresh показал X в «Спринт 2»
• THEN команда confirmed_by_state, следующая команда очереди выдаётся