sdlc-hub/openspec/changes/archive/2026-10-15-issue-card-modal/proposal.md

Why

Карточка задачи (/app/issues/{key}, change web-app #21) — отдельная страница: уход со списка или доски теряет контекст, а сама карточка плохо читается — поля одного веса, связи без темы и статуса связанной задачи, входящие связи записаны «X → тип → эта задача», техническая таблица команд на виду, форма заметок занимает пол-экрана. Комментариев задачи из Jira в карточке нет: хаб их не хранит, агент их не читает.

Решения владельца 15.10.2026 (brainstorming, jira-hub#37):

• карточку открывают, чтобы быстро понять состояние задачи (статус, кто, срок, что осталось) и разобраться в связях (что держит задачу, что ждёт её); в карточке нужны комментарии задачи из Jira с возможностью их скрыть;
• карточка открывается модальным окном поверх того места, откуда её открыли (список «Задачи» или доска), у окна свой адрес /app/issues/{key}; переходы по связям — внутри окна, «назад» браузера возвращает к прежней карточке;
• раскладка карточки — по разделу 1 дизайна (шапка состояния, связи по смыслу, заметки в режиме чтения, комментарии, второстепенное внизу); визуальные макеты не нужны, раскладку предлагает агент;
• комментарии — два change по репозиториям, сначала агент: jira-agent v10 (aep/jira-agent#27) передаёт комментарии в состоянии задачи, jira-hub (#37) хранит, отдаёт и показывает их. Требования к агенту по заведённому порядку живут в этом change (specs/agent), решения агентской части — в jira-agent/openspec/changes/agent-v10-comments/design.md.

What Changes

• Агент v10 (AGENT_VERSION = 10): refresh запрашивает в том же search поле comment; по каждой задаче передаёт comments: [{id, author, created, updated, body}] (автор — отображаемое имя, иначе логин; текст как есть); если Jira отдала не все комментарии задачи — дочитывание через GET /issue/{key}/comment. Выкатка самообновлением.
• Хаб, данные: таблица issue_comment, схема базы v2 → v3 (копия базы перед миграцией — как сейчас). Присланные комментарии задачи заменяют её прежние; задача без поля comments (агент до v10) свои комментарии не теряет. Неверная форма комментария — 422 на всю пачку POST /agent/state.
• Хаб, API: GET /issues/{key} дополнительно отдаёт comments (новые сверху), у связей — summary и status связанной задачи (null, если её нет в зеркале), epic_summary. Прежние поля не меняются.
• MCP: инструмент issue показывает 5 последних комментариев и «ещё N».
• Веб-приложение:
  • карточка задачи — модальное окно (<dialog>) поверх списка «Задачи» или доски; адрес /app/issues/{key}; прямой адрес открывает окно поверх списка задач без фильтров; закрытие (✕, Esc, щелчок по фону) возвращает туда, откуда открыли, и «назад» после закрытия карточку не открывает;
  • новая раскладка: шапка (ключ, статус Jira, статус по факту, тема, исполнитель · срок · спринт · эпик по имени, «Открыть в Jira», ✕); связи по группам «Зависит от», «Блокирует», «Связана с», «Прочие» с темой и статусом; описание свёрнуто до 8 строк; комментарии со «Скрыть/Показать», выбор запоминается в браузере; заметки в режиме чтения с «Править»; «Прочие поля»; «Команды моста» свёрнуты;
  • после сохранения заметки список задач под окном показывает новые «вид работы» и «статус по факту»; доска под окном перечитывает снимок, но её карточки берут вид работы из меток Jira, а статус — из Jira (R-7), поэтому правка заметки на карточке доски не видна.
• Спеки: agent — MODIFIED «Чтение состояния»; data-model — MODIFIED «Схема базы хаба», «Зеркало задачи»; hub-api — MODIFIED «Маршруты агента», «Маршруты интерфейсов»; mcp — MODIFIED «Инструменты»; web-app — MODIFIED «Оболочка и адреса», «Доска связей», «Список задач», «Карточка задачи», «Служебные заметки».

Non-Goals

• Запись в Jira из карточки (правка полей, статуса, добавление комментариев) — следующий change viewer-edit.
• Разбор разметки Jira (wiki) в описании и комментариях: текст показывается как есть, с переносами строк.
• Комментарии в списке задач, на доске и в GET /board.
• Изменения поведения доски, кроме открытия карточки окном и обновления заметки под окном.
• Хранение истории правок комментариев: в зеркале — последнее состояние из Jira.

Impact

• jira-agent: src/agent.py (STATE_FIELDS, to_state, дочитывание комментариев), тесты tests/test_refresh.py, фейк tests/fake_jira.py; AGENT_VERSION = 10; публикация jira-hub agent publish после merge.
• jira-hub: db.py (v3, issue_comment), mirror.py (apply_state, get_issue), api.py (h_agent_state валидация), mcp_server.py (issue), тесты; web/src/routes.tsx, shell/Layout.tsx, issues/* (окно, раскладка, заметки), board/components/Card.tsx (ссылка «ⓘ»), api/types.ts, api/queries.ts, e2e; фикстура тестового хаба с описанием, комментариями и командами.
• Порядок выкатки: агент v10 (любой хаб принимает его состояние — лишнее поле comments нынешний хаб пропускает), затем хаб; комментарии появляются после первого refresh агента v10.