docs(openspec): change bug-and-attachments — тип «Ошибка» и вложения (#43)

Дельты commands, hub-api, mcp, data-model, agent: issue_type bug с настройкой
issue_types.bug, хранилище файлов хаба (POST /files, GET /agent/files/{sha256}),
команда ensure_attachment, path в MCP batch_create, агент v11; заодно R-1
(#46) и M-1/M-2 из aep/jira-agent#30.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

openspec/changes/bug-and-attachments/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-15

openspec/changes/bug-and-attachments/design.md

@@ -0,0 +1,99 @@
+## Context
+
+Хаб `main` 68de173 (после #44), агент `main` 7d90c9b (v10). Агент на виртуалке банка ходит в хаб через общую папку UTM
+(`hub_url = folder:…`), HTTP-транспорт тоже поддерживается.
+
+Найдено при чтении кода (15.10.2026):
+- Реле папки (`relay.py`) отдаёт тело ответа строкой UTF-8 (`decode("utf-8", "replace")`), агент в HTTP-режиме понимает
+  только JSON (`Http.call`). Двоичный ответ не пройдёт ни там, ни там; JSON со строкой base64 пройдёт обоими путями.
+  Прецедент — `GET /agent/release` (`content` строкой, sha256 сверяет агент).
+- Предел тела запроса хаба `MAX_BODY = 16 МБ` (413), в реле предела нет; ответы не ограничены.
+- `command.params` (JSON) уходит в каждый `claim` и каждую довыдачу (до 3), копируется при retry, по нему ищутся
+  команды задачи (`params LIKE '%"KEY"%'`), агент пишет `params[:200]` в лог — содержимому файла там не место.
+- `issue_types` в настройках — `{task, epic}`; `issue_type_ref` агента для неизвестного типа отдаёт `{"name": None}` —
+  Jira ответит 400 без понятной причины. Зеркало хранит имя типа Jira (`issue.issue_type`), id типа не хранит; веб
+  показывает тип как есть, «Ошибка» станет обычной карточкой без доработок.
+- Подстановка `new:<n>`, зависимость от `ensure_issue` и хвостовой `refresh` работают для любого типа с полем `key` в
+  `SPEC.keys`. Старый агент на неизвестный тип отвечает `failed` «неизвестный тип команды» и не падает.
+- Подтверждения по состоянию у новых типов нет по умолчанию (`check_confirmed` → `False`).
+
+## Goals / Non-Goals
+
+**Goals:** одним пакетом из чата завести «Ошибку», поставить в спринт и приложить локальный файл; повтор пакета не
+создаёт второй задачи и второго вложения; транспорт и реле не меняются.
+
+**Non-Goals:** см. proposal (веб-загрузка, список вложений в зеркале, удаление вложений, поля по умолчанию, гейтинг по
+версии агента, файлы больше 10 МБ).
+
+## Decisions
+
+### Тип «Ошибка»
+`issue_types.bug = {name: "Ошибка", id: null}` ставится на живом хабе `settings_set`; id впишем, когда агент создаст первую
+«Ошибку» (Jira вернёт тип в задаче). Хаб проверяет наличие настройки при постановке (быстрая ошибка в чате), агент —
+при выполнении (настройку могли убрать между постановкой и выдачей).
+
+### Хранилище файлов
+Модуль `files.py` хаба: `put(content_bytes) -> (sha, size)`, `path(sha)`, `exists(sha)`, `size(sha)`, `sweep(conn, now)`.
+Каталог `<home>/files/`, имя — sha256, без имени вложения (одно содержимое может уходить под разными именами). Запись:
+временный `.<sha>.tmp` в том же каталоге, fsync, `os.replace`. Уборка — из `tick` не чаще раза в сутки: файлы старше 30
+дней по mtime; ссылки — `params` команд `ensure_attachment` в `queued`/`claimed` (поиск `json_extract(params, '$.file')`).
+Повторная загрузка того же файла обновляет mtime (`os.utime`), чтобы свежая постановка не потеряла файл в уборке.
+
+### Команда и выдача
+`SPEC["ensure_attachment"] = {required: [key, file, filename], optional: [], keys: [key], hints: {file: "sha256 из
+POST /files; в MCP — path к локальному файлу", filename: "имя вложения"}}`. Проверки типа значения — общие; формат
+`file`, наличие файла и `filename` — в проверке постановки, которой нужен каталог файлов (не в чистой `validate`, а в
+`queue.create_batch` с доступом к хранилищу). `size` дописывается при выдаче (`claim`) — там же, где `substitute`
+подставляет временные ключи; в базе `params` без `size`, поэтому retry и `GET /agent/commands/{id}` (восстановление из
+журнала — тоже с `size`) работают одинаково.
+
+### MCP
+`batch_create` до `POST /batches` обходит команды: у `ensure_attachment` с `path` читает файл (не больше 10 МБ, иначе
+ошибка до загрузки), `POST /files`, подставляет `file` и `filename` (если не задан — `Path(path).name`), удаляет `path`.
+Ошибки чтения — текст инструмента с путём, пакет не ставится. Загрузка без последующей постановки (422 из-за другой
+команды) оставляет файл в хранилище — его уберёт уборка.
+
+### Агент v11
+`do_ensure_attachment`: `GET /issue/{key}?fields=attachment` → совпадение по `filename` и `size` → `done`
+(`existed: true`); иначе `hub.file(sha)` → проверка sha256 и длины → `Jira.upload(key, filename, data)`:
+`multipart/form-data`, граница — `uuid4().hex`, часть `file` с `Content-Disposition: form-data; name="file";
+filename="<имя UTF-8>"; filename*=UTF-8''<percent-encoded>`, `Content-Type: application/octet-stream`. Таймаут загрузки —
+`max(timeout, 120)` с. Ответ Jira — список вложений, берётся `id` первого. Содержимое файла в журнал и лог не пишется.
+Заодно M-1 и M-2 из aep/jira-agent#30 в `comments_of`/`comment_state`.
+
+### Выкатка
+1. Merge PR хаба, `git pull` на Mac mini, перезапуск хаба (launchd) и MCP; `make web` не нужен (фронт не меняется).
+2. `settings_set issue_types` = `{task…, epic…, bug: {name: "Ошибка", id: null}}`.
+3. Merge PR агента, `jira-hub agent publish …/agent.py` (v11), агент обновится сам; `min_agent_version = 11`.
+4. Живая проверка: пакет «Ошибка в бэклог + вложение с кириллическим именем» на тестовой задаче, повтор пакета — без
+   дублей; тестовую задачу владелец удаляет в Jira; id типа «Ошибка» вписать в `issue_types.bug.id`.
+
+## Risks / Trade-offs
+
+- base64 даёт +33 % к размеру, файл 10 МБ — около 13,4 МБ JSON в одном файле общей папки; VirtioFS это переносит (круг
+  папки < 1 с на малых файлах, на больших — секунды), таймаут вызова агента 60 с с запасом.
+- Имя файла с кириллицей в multipart: Jira Server (commons-fileupload) читает `filename` в кодировке запроса; отправляем
+  UTF-8 и `filename*`. Проверяется только живой загрузкой (шаг 4 выкатки); если имя исказится — следующей версией агента.
+- Предел вложений Jira банка неизвестен (по умолчанию 10 МБ); больший предел банка не используется, меньший даст 413 от
+  Jira — `failed` с текстом.
+- Идемпотентность по `filename` + `size`: другой файл того же размера и с тем же именем будет принят за уже приложенный.
+
+## Decisions made without discussion
+
+1. 15.10.2026 — предел файла 10 МБ (после декодирования). Обоснование: стандартный предел вложений Jira, запас под 16 МБ
+   тела запроса хаба с base64. Цена ошибки: файл 10–16 МБ нельзя приложить через мост — поднять предел одной константой.
+2. 15.10.2026 — хранение файлов 30 дней с уборкой, кроме файлов активных команд. Обоснование: как `backup_keep` (30);
+   retry старой команды после уборки даёт понятный 422 «файл не загружен». Цена: повторная загрузка файла из чата.
+3. 15.10.2026 — пустой файл отвергается (422 `empty_file`). Обоснование: пустое вложение — почти всегда ошибка пути или
+   выгрузки. Цена: нельзя приложить пустой файл намеренно.
+4. 15.10.2026 — вложение с тем же именем, но другим размером загружается вторым вложением, старое не удаляется.
+   Обоснование: команда только добавляет недостающее, удаление в Jira — необратимая операция. Цена: два вложения с одним
+   именем, лишнее владелец удаляет руками.
+5. 15.10.2026 — `size` дописывается хабом при выдаче, а не хранится в `params`. Обоснование: retry копирует `params` и
+   проходит обычную проверку; клиент не может прислать неверный размер. Цена: выдача читает размер файла с диска.
+6. 15.10.2026 — наличие настройки `issue_types.bug` проверяют и хаб (при постановке), и агент (при выполнении).
+   Обоснование: быстрая ошибка в чате; настройку могли изменить между постановкой и выдачей. Цена: две проверки одного.
+7. 15.10.2026 — проверка наличия файла и формата `file` — в `queue.create_batch`, а не в чистой `commands.validate`.
+   Обоснование: `validate` не знает каталог данных. Цена: два места проверки параметров одной команды.
+8. 15.10.2026 — в change включены M-1 и M-2 из aep/jira-agent#30 и R-1 из aep/jira-hub#46 (по порядку, согласованному
+   владельцем 15.10.2026). M-3, M-4 из jira-agent#30 остаются в follow-up. Цена: change немного шире двух issue.

openspec/changes/bug-and-attachments/proposal.md

@@ -0,0 +1,61 @@
+## Why
+
+15.10.2026 при заведении AURORA-1639 (замечания тестирования и файл ОСВ, не прошедший распознавание) мост не справился
+с двумя вещами, и владелец доделывал руками в Jira: задачу нельзя завести типом «Ошибка» (`ensure_issue` принимает только
+`task`/`epic`), и к задаче нельзя приложить файл — такой команды нет. Баги из тестирования в AURORA заводятся типом
+«Ошибка», и к ним почти всегда прикладываются файлы (ОСВ, скриншоты). Issues: aep/jira-hub#43, aep/jira-agent#31.
+
+Решения владельца 15.10.2026 (brainstorming): файл приходит только из MCP (локальный путь в чате), веб-морда загрузку
+пока не умеет; обязательные поля у «Ошибки» те же, что у «Задачи»; файл хранится в хабе, агент забирает его отдельным
+запросом (вариант A), а не через общую папку напрямую и не base64 в параметрах команды.
+
+## What Changes
+
+- **Тип `bug`** в `ensure_issue`: настройка `issue_types.bug = {name, id}` (`id` необязателен — агент шлёт `{name}`),
+  ключи конфига `issue_type_bug`/`issue_type_bug_id` в `init`; без настройки хаб отвергает пакет 422, агент — ошибкой
+  конфигурации вместо `{"name": null}`.
+- **Хранилище файлов** в хабе: `POST /files {content: base64}` → `{file: sha256, size}`, каталог `files/` (0700), предел
+  10 МБ (413), атомарная запись, одна копия на содержимое, уборка файлов старше 30 дней без ссылок активных команд.
+  `GET /agent/files/{sha256}` — файл агенту (base64 в JSON: проходит и через реле папки, и по HTTP).
+- **Команда `ensure_attachment {key, file, filename}`**: `key` — ключ или `new:<n>`; хаб проверяет, что файл загружен,
+  при выдаче дописывает `size`; агент ищет вложение с тем же именем и размером, иначе скачивает файл у хаба, сверяет sha256
+  и загружает `multipart/form-data`. Пауза 30 с; по состоянию зеркала не подтверждается.
+- **MCP `batch_create`**: у `ensure_attachment` вместо `file` можно `path` — MCP сам загружает файл и подставляет `file`
+  и `filename`. Одним пакетом: создать «Ошибку» → поставить в спринт → приложить файл.
+- **Описание параметров и ошибки 422** (R-1 из aep/jira-hub#46): закрепить в спеке поведение, сделанное в #44 —
+  описание `batch_create` из описания параметров в коде, «ожидаются …» в ошибках валидации.
+- **Агент v11** (`AGENT_VERSION = 11`, самообновлением): тип из настроек с ошибкой конфигурации, `do_ensure_attachment`,
+  multipart на stdlib; заодно из aep/jira-agent#30 — комментарий без `id` отбрасывается с логом (M-1), 403/404 при
+  дочитывании комментариев не роняет `refresh` (M-2).
+
+## Capabilities
+
+### New Capabilities
+<!-- нет -->
+
+### Modified Capabilities
+- `commands`: тип `bug`; команда `ensure_attachment` (таблица, темп, подтверждение); проверки постановки; описание
+  параметров и текст ошибок валидации.
+- `hub-api`: `POST /files`, `GET /agent/files/{sha256}`, хранилище файлов и его уборка, 422 у `POST /batches`.
+- `mcp`: описание `batch_create` из кода; `path` у `ensure_attachment`.
+- `data-model`: `issue_types.bug` и ключи конфига.
+- `agent`: тип из настроек, выполнение `ensure_attachment`, устойчивость дочитывания комментариев, v11.
+
+## Non-Goals
+
+- загрузка файла из веб-морды и список вложений в зеркале/карточке — отдельно, когда понадобится;
+- удаление и замена вложений в Jira (команда только добавляет недостающее);
+- поля по умолчанию для типа «Ошибка» (обязательные поля как у задачи);
+- привязка выдачи команд к версии агента: старый агент отвечает `failed` «неизвестный тип команды», хватает
+  `min_agent_version = 11` (предупреждение);
+- вложения больше 10 МБ.
+
+## Impact
+
+- jira-hub: `commands.py` (SPEC, проверки), `queue.py` (дописывание `size` при выдаче), `api.py` (два маршрута, уборка
+  в `tick`), новый модуль хранилища файлов, `settings.py` (`init`), `mcp_server.py` (`path`), тесты, спеки, README,
+  ARCHITECTURE.md. Схема БД не меняется.
+- jira-agent (aep/jira-agent#31): `src/agent.py` v11, тесты и фейки (вложения в `fake_jira`, файлы в `fake_hub`),
+  README, ARCHITECTURE.md. `run.py` не меняется.
+- Выкатка: merge хаба → перезапуск хаба и MCP → `settings_set issue_types` с `bug` → `jira-hub agent publish` v11 →
+  `min_agent_version = 11` → живая проверка на тестовой задаче (удаляет владелец).

openspec/changes/bug-and-attachments/specs/agent/spec.md

@@ -0,0 +1,85 @@
+## MODIFIED Requirements
+
+### Requirement: Чтение состояния
+`refresh` SHALL выполняться запросом `search` (`jql`, `fields` = поля зеркала включая `issuelinks`, `comment` и спринт,
+`maxResults = 100`, постранично) и отправляться хабу пачками по 100 задач со связями; ключи из `issuelinks`, которых нет
+в выборке и в зеркале хаба (хаб сообщает список известных), агент SHALL дочитать одним `search` по `key in (...)`
+и отправить с признаком `neighbor`. Ошибка хаба при запросе известных ключей или отправке пачки SHALL попадать в
+`error` с префиксом «хаб: »; недоступность хаба и его 5xx повторяются, как обрыв связи, с источником «хаб».
+Каждая задача в состоянии (с v10) SHALL нести `comments` — все комментарии задачи в порядке Jira, каждый
+`{id, author, created, updated, body}`: `id` — строка; `author` — отображаемое имя автора, иначе его логин, иначе `null`;
+`created`, `updated` — время Jira как есть; `body` — текст как есть (пустой — `""`). Если `search` отдал у задачи меньше
+комментариев, чем `comment.total`, агент SHALL дочитать комментарии этой задачи через `GET /issue/{key}/comment`
+постранично (`maxResults = 100`) и передать полный список. Комментарий без `id` или с пустым `id` агент SHALL отбросить
+с записью в лог (ключ задачи), остальные передать. Если дочитывание комментариев задачи вернуло 403 или 404, агент SHALL
+передать задачу без поля `comments` (хаб оставит прежние комментарии) с записью в лог; `refresh` продолжается.
+
+#### Scenario: Полная синхронизация
+- **WHEN** `refresh {jql: "project = AURORA AND labels = AWPCA"}` при 180 задачах
+- **THEN** 2 вызова `search` + 1 на соседей; `sync_run.issues_count = 180 + соседи`
+
+#### Scenario: Хаб не ответил при отправке состояния
+- **WHEN** `refresh` через папку, реле не ответило на отправку пачки ни в одной из 4 попыток
+- **THEN** отчёт `failed` с ошибкой «результат неизвестен (обрыв связи с хабом), повтор безопасен: хаб: не ответил через
+  папку …»; в логе повторов — «обрыв связи с хабом»
+
+#### Scenario: Комментарии в состоянии
+- **WHEN** у AURORA-1620 в Jira два комментария, автор первого — `{name: "petrov", displayName: "Петров Пётр"}`, у автора
+  второго нет `displayName`, его `name` — `ivanov`
+- **THEN** в состоянии AURORA-1620 `comments` из двух элементов в порядке Jira, `author` — «Петров Пётр» и «ivanov»; число
+  вызовов `search` не изменилось
+
+#### Scenario: Неполный список комментариев
+- **WHEN** `search` вернул у AURORA-1620 20 комментариев при `comment.total = 130`
+- **THEN** агент дочитал комментарии двумя вызовами `GET /issue/AURORA-1620/comment`; в состоянии 130 комментариев
+
+#### Scenario: Комментарий без id
+- **WHEN** у задачи два комментария, у второго `id = null`
+- **THEN** в состоянии один комментарий; в логе строка с ключом задачи; пачка принята хабом
+
+#### Scenario: Нет доступа к комментариям
+- **WHEN** `GET /issue/AURORA-1620/comment` при дочитывании вернул 403
+- **THEN** AURORA-1620 в состоянии без поля `comments`; остальные задачи пачки с комментариями; `refresh` — `done`
+
+#### Scenario: Задача без комментариев
+- **WHEN** у задачи в Jira нет комментариев
+- **THEN** в её состоянии `comments = []`
+
+## ADDED Requirements
+
+### Requirement: Тип задачи и вложения
+Агент (с v11) SHALL брать тип для `ensure_issue` из `issue_types.<issue_type>`: `{id}`, если `id` задан, иначе `{name}`;
+нет записи или в ней нет ни `id`, ни `name` — ошибка конфигурации «нет настройки issue_types.<issue_type>», `failed`
+без вызова Jira.
+
+`ensure_attachment {key, file, filename, size}` (`size` дописан хабом при выдаче) агент SHALL выполнять так:
+0. `size = null` — `failed` «файл удалён с хаба, загрузите заново» без вызова Jira.
+1. `GET /rest/api/2/issue/{key}?fields=attachment`; вложение с тем же `filename` и тем же `size` есть — `done` с его
+   `attachment_id`, файл у хаба не запрашивается.
+2. Файл — `GET /agent/files/{file}`; sha256 и длина декодированного `content` SHALL совпасть с `file` и `size`, иначе —
+   временный сбой (повтор, как обрыв связи с хабом); 404 — `failed` «файл удалён с хаба, загрузите заново».
+3. `POST /rest/api/2/issue/{key}/attachments`, `multipart/form-data` с одной частью `file`, имя файла — `filename` в UTF-8
+   (`filename="…"` и `filename*=UTF-8''…`), заголовок `X-Atlassian-Token: no-check`; результат `attachment_id` из ответа.
+   Ответ Jira 4xx (в том числе 413) — `failed` с кодом и текстом Jira.
+Содержимое файла MUST NOT попадать в журнал и лог (только `file`, `filename`, размер). `AGENT_VERSION` SHALL быть 11.
+
+#### Scenario: Ошибка по имени типа
+- **WHEN** `ensure_issue {issue_type: bug, …}`, `issue_types.bug = {name: "Ошибка"}`
+- **THEN** в `POST /issue` `issuetype = {name: "Ошибка"}`
+
+#### Scenario: Нет настройки типа
+- **WHEN** `ensure_issue {issue_type: bug, …}`, в `issue_types` нет `bug`
+- **THEN** `failed` «нет настройки issue_types.bug», вызовов Jira нет
+
+#### Scenario: Загрузка вложения с кириллическим именем
+- **WHEN** `ensure_attachment {key: X, file: <sha>, filename: "ОСВ сч. 60 за 2 кв. 2026.xlsx"}`, у X вложений нет
+- **THEN** один `GET /issue/X`, один `GET /agent/files/<sha>`, один `POST /issue/X/attachments`; в Jira вложение с этим
+  именем и размером файла; отчёт `done` с `attachment_id`
+
+#### Scenario: Файл повреждён в пути
+- **WHEN** sha256 полученного `content` не равен `file`
+- **THEN** вложение в Jira не загружается; команда повторяется как при обрыве связи с хабом
+
+#### Scenario: Старый агент
+- **WHEN** агент v10 получил `ensure_attachment`
+- **THEN** `failed` «неизвестный тип команды», агент работает дальше (поведение v10, без изменений)

openspec/changes/bug-and-attachments/specs/commands/spec.md

@@ -0,0 +1,154 @@
+## 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`) | `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` | `search` с полями зеркала, по 100 на страницу; плюс дочитывание соседей по `issuelinks` | ничего в Jira; состояние уходит в хаб |
+
+Семантика `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` с ключом найденной
+
+### Requirement: Политика темпа и пауза на команде
+Хаб SHALL хранить `pacing` как минимальные зазоры в секундах по типу команды (по умолчанию: `ensure_issue` и
+`ensure_fields` 120, `ensure_comment`, `ensure_status`, `ensure_link`, `ensure_sprint`, `ensure_attachment` 30, `refresh` 2). При выдаче команды
+хаб SHALL сообщить `pause_seconds` = зазор по типу выдаваемой команды; агент SHALL выдержать его от времени своего
+последнего вызова Jira. Внутри одной команды с несколькими записями (`ensure_link` с `replace`, путь переходов) агент
+SHALL выдерживать зазор типа команды между записями.
+
+#### Scenario: Нет следующей команды — нет паузы
+- **WHEN** очередь пуста
+- **THEN** `claim` возвращает пустой ответ, агент не спит сверх долгого запроса
+
+### 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`, `ensure_attachment` и `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` перенесена на ключ
+
+## ADDED Requirements
+
+### Requirement: Описание параметров и ошибки валидации
+Описание параметров каждого типа команды (обязательные, необязательные, формат значения, условие на набор) SHALL
+храниться в коде хаба в одном месте с правилами валидации; описание инструмента MCP `batch_create` SHALL собираться из
+него (см. `mcp`). Ошибка валидации «нет <параметры>» и «лишние параметры <параметры>» SHALL заканчиваться ожидаемым
+набором параметров типа: «ожидаются <обязательные>» и, если у типа есть необязательные, «необязательные <список>».
+
+#### Scenario: Неверное имя параметра
+- **WHEN** `POST /batches` с `ensure_status {key: X, status: "Готово"}`
+- **THEN** 422 «команда 1 (ensure_status): нет target; ожидаются key, target»
+
+#### Scenario: Лишний параметр у типа с необязательными
+- **WHEN** `POST /batches` с `ensure_link {source: X, target: Y, link_type: "связанные", force: true}`
+- **THEN** 422 «команда 1 (ensure_link): лишние параметры force; ожидаются source, target, link_type; необязательные replace»
+
+### Requirement: Проверки ensure_issue с типом bug и ensure_attachment при постановке
+При постановке пакета хаб SHALL отвергать 422 без создания пакета: `ensure_issue` с `issue_type = bug`, если в настройках
+нет `issue_types.bug` с непустым `name` или `id` («нет настройки issue_types.bug»); `ensure_attachment`, если `file` — не
+64 hex-символа в нижнем регистре, файла с таким sha256 нет в хранилище хаба («файл <sha> не загружен: POST /files»),
+`filename` пустой или содержит `/` или `\`. Клиент `size` не передаёт (лишний параметр — 422). При выдаче агенту
+(`claim`, в том числе повторной) хаб SHALL добавить к параметрам `ensure_attachment` `size` — текущий размер файла в
+хранилище, или `size = null`, если файла уже нет; в базе параметры команды остаются без `size`, поэтому повтор команды
+(`POST /commands/{id}/retry`) проходит проверку как новая.
+
+#### Scenario: Ошибка без настройки типа
+- **WHEN** `POST /batches` с `ensure_issue {issue_type: bug, …}`, в `issue_types` только `task` и `epic`
+- **THEN** 422 «команда 1: нет настройки issue_types.bug», пакет не создан
+
+#### Scenario: Вложение без загруженного файла
+- **WHEN** `POST /batches` с `ensure_attachment {key: X, file: <64 hex>, filename: "a.xlsx"}`, файла нет в хранилище
+- **THEN** 422 «команда 1: файл <sha> не загружен: POST /files», пакет не создан
+
+#### Scenario: Ошибка с вложением одним пакетом
+- **WHEN** пакет `[ensure_issue {temp_key: new:1, issue_type: bug, …}, ensure_sprint {key: new:1, sprint: "Спринт 2"},
+  ensure_attachment {key: new:1, file: <sha>, filename: "ОСВ 60.xlsx"}]`, файл загружен
+- **THEN** пакет создан; `ensure_attachment` выдаётся после завершения `ensure_issue` с подставленным ключом и `size` файла

openspec/changes/bug-and-attachments/specs/data-model/spec.md

@@ -0,0 +1,24 @@
+## MODIFIED Requirements
+
+### Requirement: Настройки
+Таблица `setting` SHALL хранить парами ключ–JSON: `base_jql`, `field_ids`, `issue_types`, `priority_map`, `link_types`,
+`transitions_map`, `pacing`, `board_id`, `tokens` (агентский и клиентский), `settings_version` (увеличивается при любой
+правке), `backup_keep`, `auto_refresh_minutes`, `relay_dir` (абсолютный путь папки реле или `null`, по умолчанию `null`;
+относительный путь и не-строка при записи — 422; агенту не передаётся). Спринты агент читает с доски `board_id`,
+отдельной настройки имён спринтов нет. Начальные значения SHALL импортироваться из `admin/jira-sync/config.example.json`
+командой `jira-hub init`; пароль и логин Jira в настройках MUST NOT присутствовать. `issue_types` — объект
+`{task, epic, bug}`, у каждого `{name, id}` (`id` может быть `null`); `init` берёт их из ключей конфига
+`issue_type_<тип>` и `issue_type_<тип>_id`; `bug` попадает в `issue_types`, только если в конфиге есть хотя бы
+один из ключей `issue_type_bug`, `issue_type_bug_id` (`task` и `epic` — как раньше, всегда).
+
+#### Scenario: Правка настроек поднимает версию
+- **WHEN** через API изменён `pacing`
+- **THEN** `settings_version` увеличен, следующий `claim` отдаёт агенту новую версию
+
+#### Scenario: Конфиг без ключей ошибки
+- **WHEN** `jira-hub init --config` с `issue_type_task`, `issue_type_epic`, без `issue_type_bug`
+- **THEN** `issue_types` содержит `task` и `epic`, `bug` нет; постановка `ensure_issue` с `issue_type = bug` — 422
+
+#### Scenario: Неверный relay_dir
+- **WHEN** `PUT /settings` с `relay_dir = "rshb/jira-bridge"`
+- **THEN** 422, значение не записано, `settings_version` не изменился

openspec/changes/bug-and-attachments/specs/hub-api/spec.md

@@ -0,0 +1,167 @@
+## MODIFIED Requirements
+
+### Requirement: Маршруты агента
+Хаб SHALL предоставлять агенту следующие маршруты (все под агентским токеном):
+- `POST /agent/claim` `{agent_version, settings_version, last_jira_call_at, update_state, launcher_version}` — долгий
+  запрос до 30 с; ответ `{command: {id, type, params, pause_seconds}, settings_version, agent_release}` или `{command:
+  null, settings_version, agent_release}`, где `agent_release` — `{version, sha256}` опубликованной версии агента или
+  `null`; обновляет `agent_status` (`last_jira_call_at = null` не затирает прежнее значение). `update_state` (объект или
+  `null`, `error` хранится до 500 символов) и `launcher_version` (целое или `null`) необязательны; хаб SHALL хранить
+  последние значения в памяти процесса, значения неверного типа игнорировать, не отвергая `claim`. Если есть команда в
+  `claimed`, `claim` SHALL выдать её снова (повторная выдача, см. `commands`), а не следующую из очереди.
+- `GET /agent/settings` — настройки для агента (без токенов).
+- `GET /agent/commands/{id}` — команда по id (для восстановления из журнала), включая `pause_seconds`.
+- `POST /agent/commands/{id}/result` `{status, result, error, jira_calls, rate_limited}` — идемпотентно: повторный
+  отчёт по команде в терминальном статусе отвечает 200 без изменений, кроме позднего отчёта `done` с `result.key` по
+  `ensure_issue` в `cancelled` или `failed` без результата (результат записывается, статус не меняется, заметка `new:N`
+  переносится на ключ). Отчёт по команде в `queued` SHALL отвергаться 409 `not_claimed`. `error` хаб SHALL обрезать до
+  1500 символов.
+- `POST /agent/state` `{command_id, issues: [...], links: [...], neighbor_keys: [...], page, last_page}` — загрузка состояния
+  пачками; `neighbor_keys` — ключи вне базовой JQL, дочитанные по связям; хаб обновляет зеркало и `sync_run`. Каждая
+  пачка применяется независимо; `page` и `last_page` необязательны и хабом не используются. Поле задачи `comments`
+  необязательно; если оно есть, хаб SHALL до записи проверить его форму: список объектов, `id` — непустая строка, `body` —
+  строка, `author`, `created`, `updated` — строка или `null`; нарушение — 422 `bad_state` с ключом задачи и именем поля,
+  пачка не применяется.
+- `GET /agent/known-keys` — ключи зеркала (для определения соседей).
+- `GET /agent/release` — опубликованная версия агента `{version, sha256, content}` (`content` — текст `agent.py`);
+  нет публикации или файл не сходится с манифестом по sha256 — 404 `no_release`.
+- `GET /agent/files/{sha256}` — файл вложения из хранилища хаба `{file, size, content}` (`content` — base64 содержимого);
+  файла нет — 404 `no_file`.
+
+#### Scenario: Выдача с подстановкой ключа
+- **WHEN** следующая команда ссылается на `new:60`, а `ensure_issue` для `new:60` завершилась с `AURORA-1590`
+- **THEN** `claim` отдаёт команду с `AURORA-1590` в параметрах
+
+#### Scenario: Повторный отчёт
+- **WHEN** агент дважды прислал `result` для команды 15
+- **THEN** второй ответ 200, статус и результат не изменились
+
+#### Scenario: Отчёт по невыданной команде
+- **WHEN** `POST /agent/commands/16/result` с `status = done`, команда 16 в `queued`
+- **THEN** 409 `not_claimed`, команда осталась `queued`
+
+#### Scenario: Длинная ошибка
+- **WHEN** агент прислал `failed` с `error` длиной 5000 символов
+- **THEN** в `command.error` первые 1500 символов
+
+#### Scenario: Поздний отчёт после предела выдач
+- **WHEN** `ensure_issue {temp_key: new:8, …}` переведена хабом в `failed` «агент не отчитался после 3 выдач», затем агент
+  прислал `done` с `result.key = AURORA-1630`
+- **THEN** команда `failed`, в `result` — `AURORA-1630`; заметка `new:8` перенесена на `AURORA-1630`
+
+#### Scenario: Публикация в ответе claim
+- **WHEN** опубликована v6, агент v5 отправил `claim`, команд нет
+- **THEN** ответ `{command: null, settings_version, agent_release: {version: 6, sha256: …}}`
+
+#### Scenario: Состояние обновления от агента
+- **WHEN** агент прислал в `claim` `update_state = {state: rolled_back, from_version: 6, to_version: 7, error: "код 1 через 3 с"}`
+  и `launcher_version = 1`
+- **THEN** `GET /agent` отдаёт это `update_state`, `launcher_version = 1` и `update_hint` «откат с v7 на v6: код 1 через 3 с»
+
+#### Scenario: Скачивание версии
+- **WHEN** агентским токеном `GET /agent/release`, опубликована v6
+- **THEN** 200 `{version: 6, sha256, content}`, sha256 от `content` в UTF-8 равен `sha256`; клиентским токеном — 401;
+  без публикации — 404 `no_release`
+
+#### Scenario: Скачивание файла вложения
+- **WHEN** агентским токеном `GET /agent/files/<sha>`, файл загружен
+- **THEN** 200 `{file: <sha>, size, content}`, sha256 от декодированного `content` равен `<sha>`; клиентским токеном — 401;
+  файла нет — 404 `no_file`
+
+#### Scenario: Неверный комментарий в пачке
+- **WHEN** `POST /agent/state` с задачами X и Y, у Y комментарий `{id: "7", body: 42}`
+- **THEN** 422 `bad_state` с ключом Y и полем `body`; ни X, ни Y в зеркале не изменились
+
+### Requirement: Маршруты интерфейсов
+Хаб SHALL предоставлять интерфейсам (MCP, позже просмотрщик) следующие маршруты под клиентским токеном:
+- `GET /issues` с фильтрами `sprint`, `assignee`, `work_kind`, `fact_status`, `status`, `label`, `epic`, `neighbor`,
+  `q` (подстрока темы), `limit`/`offset` — строки зеркала (все поля `issue`) с `fact_status` и `work_kind` из заметок;
+  сокращение до карточки — дело интерфейса.
+- `GET /issues/{key}` — задача целиком: поля, `epic_summary` (тема эпика из зеркала или `null`), связи в обе стороны
+  (`links_out: [{target_key, link_type, summary, status}]`, `links_in: [{source_key, link_type, summary, status}]`, где
+  `summary` и `status` — связанной задачи из зеркала или `null`, если её там нет), заметки, последние 10 команд по ней,
+  `comments: [{comment_id, author, created, updated, body}]` — все комментарии, новые сверху (по `created`, затем
+  `comment_id`, по убыванию).
+- `PUT /issues/{key}/note` — заметки (частичное обновление, `updated_by` из тела).
+- `POST /batches` `{title, author, commands: [...]}` → `{id, estimate_seconds}`; 422 при неизвестном типе, неверных
+  параметрах (в том числе неверного типа значения), временном ключе без `ensure_issue`, двух и более `ensure_issue` с
+  одинаковой `summary` (сравнение после обрезки пробелов по краям; в ответе перечислены повторяющиеся темы), а также
+  по проверкам постановки из `commands` (тип `bug` без настройки, файл вложения не загружен).
+- `POST /files` `{content}` (`content` — base64 содержимого файла) → `{file, size}`, где `file` — sha256 содержимого
+  (64 hex-символа, нижний регистр); см. «Хранилище файлов вложений».
+- `GET /batches?limit=`, `GET /batches/{id}` (с командами), `POST /batches/{id}/cancel` — отменяет `queued` команды
+  пакета; ответ — вид пакета с полем `still_claimed`: список `{id, type}` команд пакета в `claimed` (они будут выполнены
+  агентом; остановить — отмена команды с `force`).
+- `POST /commands/{id}/retry` — новая команда с теми же параметрами в новом пакете «Повтор команды N».
+- `POST /commands/{id}/cancel` — только для `queued`; для `claimed` — 409, если не передан `force: true`.
+- `POST /refresh` `{keys | jql | full: true}` → пакет из одного `refresh`.
+- `GET /agent`, `GET /sync-runs?limit=`, `GET /settings`, `PUT /settings` (частично; поднимает `settings_version`;
+  ответ — все настройки после записи, как у `GET /settings`, включая `settings_version`).
+
+#### Scenario: Фильтр по спринту
+- **WHEN** `GET /issues?sprint=Спринт 2`
+- **THEN** только задачи с таким `sprint`, отсортированы по сроку, затем по ключу
+
+#### Scenario: Отмена взятой команды
+- **WHEN** `POST /commands/15/cancel` без `force`, команда `claimed`
+- **THEN** 409 с `claimed_at`; с `force: true` — `cancelled`, следующий отчёт агента по ней принимается, статус не меняется
+
+#### Scenario: Поздний отчёт по отменённому созданию
+- **WHEN** `ensure_issue {temp_key: new:7, …}` отменена с `force: true`, затем агент прислал `done` с `result.key = AURORA-1620`
+- **THEN** команда `cancelled`, в `result` — `AURORA-1620`; заметка `new:7` перенесена на `AURORA-1620`
+
+#### Scenario: Дубль темы в пакете
+- **WHEN** `POST /batches` с двумя `ensure_issue`, у обеих `summary = "Шахматка: комментарии"`
+- **THEN** 422 с темой «Шахматка: комментарии», пакет не создан
+
+#### Scenario: Тема не строка
+- **WHEN** `POST /batches` с `ensure_issue {temp_key: new:1, summary: 42, …}`
+- **THEN** 422 с указанием параметра `summary`, пакет не создан
+
+#### Scenario: Отмена пакета с командой у агента
+- **WHEN** в пакете 9 команда 30 `claimed`, команды 31 и 32 `queued`; `POST /batches/9/cancel`
+- **THEN** 31 и 32 `cancelled`; в ответе `still_claimed = [{id: 30, type: …}]`; 30 остаётся `claimed`
+
+#### Scenario: Ответ на запись настроек
+- **WHEN** `PUT /settings {relay_dir: "/Volumes/externalSSD/utm/rshb/jira-bridge"}`
+- **THEN** 200; ответ содержит `relay_dir` с записанным значением, новую `settings_version` и остальные настройки;
+  токенов в ответе нет
+
+#### Scenario: Карточка с комментариями и связями
+- **WHEN** у AURORA-9001 два комментария (14.10 и 15.10), исходящая связь на AURORA-9002 («API свода», «Новая») и на
+  AURORA-1, которой нет в зеркале; эпик AURORA-9100 «Тестовый эпик»
+- **THEN** `GET /issues/AURORA-9001` отдаёт `comments` с комментарием от 15.10 первым, у связи на AURORA-9002 —
+  `summary = "API свода"`, `status = "Новая"`, у связи на AURORA-1 — `summary = null`, `status = null`;
+  `epic_summary = "Тестовый эпик"`
+
+## ADDED Requirements
+
+### Requirement: Хранилище файлов вложений
+Хаб SHALL хранить файлы вложений в каталоге `files/` внутри каталога данных, по одному файлу на содержимое с именем
+sha256 (без расширения и имени вложения: имя задаёт команда). Каталог SHALL иметь права `0700` (выставляются при создании
+и при каждом старте, как у `backups/`). `POST /files`:
+- `content` не строка или не base64 — 400 `bad_request`; пустой файл — 422 `empty_file`;
+- файл больше 10 МБ (10 485 760 байт) после декодирования — 413 `too_large` (тело запроса до 16 МБ проходит);
+- запись атомарная: временный файл в `files/`, затем переименование; повторная загрузка того же содержимого отвечает тем
+  же `file` и не создаёт второй копии.
+Файлы в бэкапы базы MUST NOT входить. Фоновый `tick` хаба SHALL не чаще раза в сутки удалять файлы старше 30 дней (по
+времени изменения), на которые не ссылается ни одна команда `ensure_attachment` в `queued` или `claimed`; повтор команды
+после уборки отвергается при постановке 422 «файл <sha> не загружен: POST /files». Повторная загрузка того же
+содержимого SHALL обновлять время изменения файла.
+
+#### Scenario: Загрузка файла
+- **WHEN** `POST /files {content: base64("abc")}`
+- **THEN** 200 `{file: "ba7816bf…", size: 3}`; в `files/` файл `ba7816bf…` с содержимым `abc`
+
+#### Scenario: Повторная загрузка
+- **WHEN** тот же `POST /files` второй раз
+- **THEN** 200 с тем же `file`; в `files/` по-прежнему один файл
+
+#### Scenario: Слишком большой файл
+- **WHEN** `POST /files` с файлом 11 МБ
+- **THEN** 413 `too_large`, в `files/` ничего не появилось
+
+#### Scenario: Уборка старых файлов
+- **WHEN** в `files/` файл A старше 30 дней без ссылок, файл B старше 30 дней, на него ссылается `ensure_attachment` в
+  `queued`, файл C загружен вчера
+- **THEN** после уборки удалён только A

openspec/changes/bug-and-attachments/specs/mcp/spec.md

@@ -0,0 +1,71 @@
+## MODIFIED Requirements
+
+### Requirement: Инструменты
+| Инструмент | Параметры | Результат |
+|---|---|---|
+| `issues` | фильтры как у `GET /issues`, `limit` (по умолчанию 50) | таблица: ключ, тема (до 80 символов), статус, срок, исполнитель, спринт, статус по факту |
+| `issue` | `key` | поля, связи (обе стороны, с типом и направлением), заметки, последние команды, комментарии: «комментарии (N):» и 5 последних (автор, время, текст до 300 символов с «…»), «ещё M», если их больше 5; без комментариев — «комментариев нет» |
+| `notes_set` | `key`, подмножество полей заметок | обновлённые заметки |
+| `batch_create` | `title`, `commands` (список объектов по контракту `commands`; у `ensure_attachment` вместо `file` можно `path`) | `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<N> от <дата>» или «публикации нет»), состояние обновления («обновление: <state> v<from> → v<to>»), запускатель («запускатель: v<N>», «без запускателя» или, пока `agent_reported = false`, «запускатель: неизвестно (агент ещё не выходил на связь после перезапуска хаба)»), `update_hint`, если он есть |
+| `sync_log` | `limit` | последние `sync_run` |
+| `settings_get`, `settings_set` | ключ, значение | текущее значение / новая `settings_version` |
+
+Описание инструмента `batch_create` SHALL перечислять параметры каждого типа команды (обязательные, необязательные в
+`[ ]`, формат значения) и собираться из описания параметров в коде хаба (см. `commands`), а не вручную.
+
+`ensure_attachment` в `batch_create` SHALL принимать вместо `file` параметр `path` — абсолютный путь к локальному файлу на
+машине MCP-сервера. До постановки пакета MCP SHALL прочитать файл, загрузить его `POST /files` и заменить `path` на
+`file`; `filename` по умолчанию — имя файла из `path`. Нет файла, нет прав, не файл, больше 10 МБ — ответ инструмента
+с причиной и путём, пакет не ставится. Передан и `path`, и `file` — ответ «у ensure_attachment либо path, либо file».
+
+Описание инструмента `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_create {title: "Ошибка ОСВ 60", commands: [ensure_issue{temp_key: new:1, issue_type: bug, …},
+  ensure_attachment{key: new:1, path: "/Users/…/ОСВ сч. 60 за 2 кв. 2026.xlsx"}]}`
+- **THEN** файл загружен в хаб; пакет создан с `ensure_attachment {key: new:1, file: <sha>, filename: "ОСВ сч. 60 за 2 кв.
+  2026.xlsx"}` и хвостовым `refresh`
+
+#### Scenario: Файла нет
+- **WHEN** тот же вызов, файла по `path` нет
+- **THEN** ответ «файл не найден: <path>», пакет не создан, в хаб ничего не загружено
+
+#### 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»