## Context `main` 13e6c16. Устройство, на которое опираются правки: - **Агент** (`jira-agent/src/agent.py`, v9): `refresh` читает задачи `search` с `fields = STATE_FIELDS` (+ плановые даты и поле эпика), `to_state` собирает словарь задачи, пачки по 100 уходят в `POST /agent/state`. Комментарии агент читает только в `ensure_comment` (`GET /issue/{key}/comment`, постранично по 100). - **Хаб**: `mirror.apply_state` пишет в `issue` только столбцы `ISSUE_COLUMNS` — лишние поля задачи (в том числе будущее `comments`) молча пропускаются, поэтому агент v10 совместим с нынешним хабом. `mirror.get_issue` отдаёт задачу, связи (`target_key`/`source_key`, `link_type`), заметку, 10 последних команд. Схема базы — v2 (`db.SCHEMA_VERSION`), миграция с копией базы — `db.migrate`. Тело запроса ограничено 16 МБ (`api.MAX_BODY`). - **Веб-приложение**: `createBrowserRouter(routes, {basename: "/app"})`; `Layout` с ``; маршруты `board`, `issues`, `issues/:key` (страница `IssuePage`). Ссылки на карточку — ключ в `IssuesPage` и «ⓘ» в `board/components/ Card.tsx`. `NoteForm` — форма заметок с `useBlocker` (смена `pathname` при правках требует подтверждения) и `beforeunload`. `useSaveNote` после успеха обновляет кэш задачи и инвалидирует `["issues"]` и `board`. Прокрутка доски при возврате на `/app/board` восстанавливается (M-3 #29). - **Справочники**: `link_types` настроек — логическое имя → тип Jira (`блокирует начало` → `ASUPR_Блокер_Начала`, `блокирует завершение` → `ASUPR_Блокер_Завершения`, `связанные` → `ASUPR_Связанные`); `status_labels` — статус по факту → класс (`fact-done`, `fact-cancelled`, …). ## Goals / Non-Goals **Goals:** карточка открывается окном поверх списка и доски без потери их состояния; по шапке видно состояние задачи, по связям — что держит задачу и что ждёт её, с темой и статусом связанных; комментарии задачи из Jira в карточке со скрытием; агент v10 и хаб совместимы в любом порядке выкатки. **Non-Goals:** см. proposal.md. ## Decisions ### Агент v10 (решения агентской части — `jira-agent/openspec/changes/agent-v10-comments/design.md`) 1. **Поле `comment` в том же `search`.** `STATE_FIELDS` получает `comment`; новых вызовов Jira на обычную задачу нет. Jira Server отдаёт `fields.comment = {comments: [...], total, maxResults, startAt}`. 2. **Дочитывание.** Если `len(comments) < total`, агент читает комментарии этой задачи `GET /issue/{key}/comment` (`startAt`, `maxResults = 100`) до конца и берёт их вместо частичного списка. Вызовы учитываются в темпе и 429 как любые вызовы Jira. 3. **Форма.** `comments: [{id, author, created, updated, body}]` в порядке Jira (старые первыми): `id` — строка, `author` — `author.displayName`, иначе `author.name`, иначе `null`; `created`/`updated` — строки Jira как есть; `body` — текст как есть (`""`, если в Jira пусто). Поле `comments` есть у каждой задачи, прочитанной агентом v10 (пустой список — комментариев нет). 4. **Версия и выкатка.** `AGENT_VERSION = 10`; после merge PR агента — `jira-hub agent publish src/agent.py` (пишет в каталог живого хаба: выполняет владелец или агент по его отдельной команде). ### Хаб 5. **Таблица `issue_comment`** `(key, comment_id, author, created, updated, body, PRIMARY KEY (key, comment_id))`; выборка по `key` идёт по первичному ключу, отдельный индекс не нужен. Схема v3; миграция v2 → v3 создаёт таблицу (копия базы `schema-v2` — существующим механизмом). 6. **Запись.** `apply_state`: для задачи с полем `comments` (список) комментарии этой задачи удаляются и вставляются присланные — в одной транзакции с задачей; задача без поля `comments` своих комментариев не теряет (агент до v10). 7. **Проверка формы** в `h_agent_state` до записи: `comments` — список объектов; `id` — непустая строка; `body` — строка; `author`, `created`, `updated` — строка или `null`. Нарушение — 422 `bad_state` с ключом задачи и полем, пачка не применяется целиком (агент получает ошибку хаба в отчёте `refresh`). 8. **`GET /issues/{key}`**: добавляются `comments` (новые сверху: по `created` убыв., затем `comment_id` убыв.), `epic_summary` (тема задачи-эпика из зеркала или `null`), у каждой связи — `summary` и `status` связанной задачи (`LEFT JOIN issue`, `null`, если её нет в зеркале). Прежние поля и их форма не меняются. 9. **MCP `issue`**: после заметок — «комментарии (N):» и 5 последних (автор, время, текст до 300 символов с «…»), затем «ещё M», если их больше 5; нет комментариев — «комментариев нет». ### Веб-приложение: окно 10. **Фоновая страница.** Ссылки на карточку (ключ в списке, «ⓘ» на доске, связи в карточке) передают в `location.state` `{background, depth, direct}`: `background` — адрес страницы под окном (`pathname + search`), `depth` — сколько записей истории занято карточками поверх неё (1 при открытии со страницы, +1 при переходе по связи), `direct` — окно открыто прямым адресом (переносится в переходы по связям). Маршрут верхнего уровня — `{path: "*", element: }`; `Layout` всегда рисует страницы через `useRoutes(PAGE_ROUTES, pageLocation)` с явным адресом: `background` при открытом окне, иначе текущий адрес. Явный адрес нужен всегда: так дерево компонентов страницы не меняется при открытии окна (страница не пересоздаётся), а `useSearchParams`/`useLocation` внутри фоновой страницы видят её собственный адрес, и фильтры списка не сбрасываются. Состояние страницы (фильтры, загруженные порции, прокрутка, раскладка доски, опрос пакета) сохраняется. `ErrorBoundary` страницы получает ключ по адресу страницы, у окна — свой. 11. **Прямой адрес** `/app/issues/{key}` без `state` (новая вкладка, закладка): `Layout` заменяет запись истории тем же адресом со `state = {background: /issues, depth: 0, direct: true}`; под окном — список задач без фильтров. Перезагрузка страницы с открытым окном сохраняет `state` (браузер хранит его в записи истории). 12. **Закрытие** (✕, Esc, щелчок по фону): `depth = 0` — `navigate("/issues", {replace: true})`; `depth ≥ 1` — `navigate(-depth)`, браузер возвращается к записи страницы под окном, и «назад» после закрытия ведёт на шаг раньше неё; если окно было открыто прямым адресом (`direct`), запись прямого адреса, на которую вернулись, заменяется на `/issues` (`replace`). Закрытие проходит через блокировщик заметок (п. 14). Вкладки «Доска»/«Задачи» в шапке подсвечиваются по адресу страницы под окном. 13. **Элемент `