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

ADDED Requirements

Requirement: Пакет проекта

Пакет, поставленный с project = P (см. hub-api), SHALL проходить при постановке, до записи, проверки проекта; любая неудача — 422 с ключом задачи и причиной, пакет не создаётся:

• P нет среди проектов — 422;
• ensure_issue: если в labels нет P, хаб SHALL дописать P в конец labels (в базе параметры хранятся уже с ней; без labels — labels = [P]); метка, совпадающая с P без учёта регистра, но не точно, SHALL заменяться на P; метка другого проекта в labels — 422;
• ensure_fields: P в labels_remove или метка другого проекта в labels_add — 422;
• ensure_fields, ensure_comment, ensure_status, ensure_sprint, ensure_attachment: key SHALL быть временным ключом ensure_issue этого пакета или задачей зеркала с меткой P, иначе 422 « не в проекте P»;
• ensure_link: хотя бы один из source, target — временный ключ этого пакета или задача зеркала с меткой P;
• refresh — без проверок проекта. «Метка другого проекта» и «P в labels_remove» SHALL сравниваться без учёта регистра; принадлежность задачи проекту (метка P у задачи зеркала) — точным совпадением, как в разрезе проекта. Пакет без project эти проверки не проходит, метки хаб в нём не дописывает.

Scenario: Метка проекта дописана

• WHEN пакет с project = STOCKS_DRRK, ensure_issue {temp_key: new:1, summary: "Сверка остатков", labels: ["kind-dev"]}
• THEN пакет создан; в параметрах команды labels = ["kind-dev", "STOCKS_DRRK"]

Scenario: Чужая метка проекта

• WHEN пакет с project = STOCKS_DRRK, ensure_issue {…, labels: ["awpca"]}, есть проект AWPCA
• THEN 422 «метка другого проекта: awpca», пакет не создан

Scenario: Задача другого проекта

• WHEN пакет с project = STOCKS_DRRK, ensure_fields {key: AURORA-1538, duedate: …}, у AURORA-1538 метка только AWPCA
• THEN 422 «AURORA-1538 не в проекте STOCKS_DRRK»

Scenario: Связь с соседом

• WHEN пакет с project = STOCKS_DRRK, ensure_link {source: AURORA-1 (метка STOCKS_DRRK), target: AURORA-1538 (метка AWPCA), …}
• THEN пакет создан

MODIFIED Requirements

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

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

Тип	Параметры	Что читает	Что пишет
ensure_issue	temp_key (new:<n>), issue_type (task/epic/bug), summary, description, priority, duedate, planned_start, planned_end, labels, epic_key, assignee	поиск project = <proj> AND reporter = currentUser() AND created >= -7d, точное сравнение summary	при отсутствии — POST /issue с типом из issue_types.<issue_type> (для эпика — с 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); board_id хаб дописывает при постановке (от клиента — 422)	GET /issue/{key} (поле спринта), список спринтов доски board_id (активные и будущие)	POST /rest/agile/1.0/sprint/{id}/issue или POST /rest/agile/1.0/backlog/issue
ensure_attachment	key, file (sha256 файла в хранилище хаба, 64 hex-символа), filename (имя вложения в Jira, без /, \, " и управляющих символов); size хаб дописывает при выдаче	GET /issue/{key}?fields=attachment	вложения с тем же filename и размером нет — файл у хаба (GET /agent/files/{file}), затем POST /issue/{key}/attachments (multipart); есть — ничего; результат attachment_id
refresh	keys (список) или jql; boards ([{id, type}] — доски проектов, type — scrum, kanban или null) хаб дописывает при выдаче	search с полями зеркала, по 100 на страницу; плюс дочитывание соседей по issuelinks; доски с неизвестным типом — GET /rest/agile/1.0/board/{id}	ничего в Jira; состояние уходит в хаб; результат — `boards: {"": "scrum"

Доску для ensure_sprint хаб SHALL определять при постановке: проект задачи — проекты, чьи метки есть у задачи в зеркале (для временного ключа — в labels её ensure_issue в пакете, после дописывания метки проекта); board_id — доска этого проекта. 422 при постановке: задача ни в одном проекте; в нескольких проектах с разными досками; у проекта нет доски; тип доски kanban («у проекта P канбан-доска, спринтов нет»); тип доски ещё не известен («тип доски проекта P ещё не известен — дождитесь обновления из Jira»). boards у refresh хаб SHALL дописывать при каждой выдаче (в базе не хранится): все доски проектов без повторов. По результату refresh хаб SHALL записать присланные типы scrum и kanban в проекты с этой доской; null тип не меняет.

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

Текст описания (ensure_fields) и тело комментария (ensure_comment) агент SHALL сравнивать с текущим значением в Jira без различия переводов строк \r\n и \n; записывается текст команды как есть. Jira хранит присланный текст, а правленный в веб-интерфейсе — с \r\n (проверено на Jira банка 13.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_fields {key: X, description: "а\nб"}, а в Jira описание X — "а\r\nб"
• THEN агент не делает PUT, отчёт done с changed = []

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 {temp_key: new:1, issue_type: bug, summary: "ОСВ 60 не распознана", labels: [AWPCA]}, в настройках issue_types.bug = {name: "Ошибка"} без id
• THEN агент создаёт задачу с issuetype = {name: "Ошибка"}; отчёт done с ключом

Scenario: Вложение уже есть

• WHEN ensure_attachment {key: X, file: <sha>, filename: "ОСВ 60.xlsx"}, у X в Jira есть вложение «ОСВ 60.xlsx» того же размера
• THEN агент не скачивает файл у хаба и не загружает его в Jira; отчёт done с attachment_id найденного, jira_calls = 1

Scenario: Вложение с тем же именем, другого размера

• WHEN та же команда, у X есть «ОСВ 60.xlsx» другого размера
• THEN агент загружает файл вторым вложением с тем же именем (Jira это допускает); отчёт done с новым attachment_id

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

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

Scenario: Спринт задачи проекта

• WHEN у AURORA-1538 метка AWPCA, проект AWPCA с доской 4216 типа scrum; ensure_sprint {key: AURORA-1538, sprint: "Спринт 2"}
• THEN пакет создан, в параметрах команды board_id = 4216

Scenario: Спринт на канбане

• WHEN у AURORA-1 метка STOCKS_DRRK, доска проекта — kanban; ensure_sprint {key: AURORA-1, sprint: "Спринт 2"}
• THEN 422 «у проекта STOCKS_DRRK канбан-доска, спринтов нет»

Scenario: Тип доски определён

• WHEN проект STOCKS_DRRK с доской 5120 и board_type = null; выдаётся refresh, агент вернул boards: {"5120": "kanban"}
• THEN при выдаче в параметрах boards есть {id: 5120, type: null}; после отчёта у проекта board_type = kanban