sdlc-hub/openspec/changes/hub-hygiene-d/specs/commands/spec.md

MODIFIED Requirements

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

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

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

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

Scenario: Создание отменено

• WHEN пакет: ensure_issue {temp_key: new:901, …} (отменена с force: true), ensure_comment {key: new:901, …}
• THEN ensure_comment — skipped с ошибкой «создание задачи new:901 отменено»

Scenario: Создание упало

• WHEN ensure_issue {temp_key: new:902, …} завершилась failed, зависимая ensure_link {source: new:902, …}
• THEN ensure_link — skipped с ошибкой «задача new:902 не создана»

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

Ошибка команды SHALL записываться в error (HTTP-код, текст Jira); хаб SHALL хранить не больше 1500 символов error, обрезая присланное. Пакет после ошибки продолжается.

Повторная выдача. Агент запрашивает новую команду, только когда у него нет незавершённой (см. agent), поэтому команда в claimed к моменту следующего claim считается не доставленной или потерянной агентом. При claim хаб SHALL сначала выдать снова самую старую (по claimed_at, затем id) команду в claimed: тот же id и параметры, pause_seconds по текущей политике темпа, новый claimed_at, deliveries + 1. Если у неё уже deliveries >= 3, хаб SHALL перевести её в failed с error = "агент не отчитался после 3 выдач" и перейти к следующей (довыдача другой claimed или следующая queued). Довыдача — доставка той же выдачи, а не повтор команды: новых команд хаб MUST NOT создавать сам, повтор после failed — новая команда с теми же параметрами по запросу интерфейса. Если агент всё же отчитался done с ключом по ensure_issue, переведённой в failed по пределу, хаб SHALL записать ключ в результат и перенести заметку, не меняя статус (как для отменённой, см. hub-api).

Подтверждение по состоянию. Если после любого refresh желаемый результат команды в claimed виден в зеркале, хаб SHALL перевести её в confirmed_by_state: ensure_fields — все поля совпадают (строки сравниваются без различия \r\n и \n; null и пустая строка равны); ensure_status — статус равен последнему в пути; ensure_link — связь есть и конфликтов нет; ensure_sprint — спринт совпадает. ensure_issue, ensure_comment и refresh по состоянию не подтверждаются: потерянный отчёт по ним закрывается повторной выдачей (агент находит созданную задачу поиском дубля) или отменой человеком.

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

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

Scenario: Описание с CRLF в зеркале

• WHEN ensure_fields {key: X, description: "a\nb"} в claimed, после refresh в зеркале у X description = "a\r\nb"
• THEN команда confirmed_by_state

Scenario: Ответ на claim потерян

• WHEN команда 40 выдана (deliveries = 1), ответ до агента не дошёл, агент снова прислал claim
• THEN claim отдаёт команду 40, deliveries = 2; в очереди есть queued команды, но выдаётся 40

Scenario: Предел выдач

• WHEN команда 41 в claimed с deliveries = 3, агент снова прислал claim, в очереди есть команда 42
• THEN 41 — failed «агент не отчитался после 3 выдач»; claim отдаёт 42

Scenario: Потерянный отчёт о создании задачи

• WHEN ensure_issue {temp_key: new:5, summary: "Отчёт"} выполнена агентом, отчёт не дошёл, агент прислал claim
• THEN команда выдаётся снова; агент находит созданную задачу поиском дубля и отчитывается done с её ключом; второй задачи нет, заметка new:5 перенесена на ключ