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

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 → живая проверка на тестовой задаче (удаляет владелец).