sdlc-hub/openspec/changes/change-history/proposal.md

Why

Зеркало хаба хранит только текущее состояние задачи: при каждом обновлении строка issue перезаписывается, прежние значения теряются. Владелец хочет быстро видеть, что произошло с задачами за последние часы или за сегодня — что закрылось, у чего поменялось описание, где появился комментарий, у чего сдвинулись сроки, — и как менялась конкретная задача.

Решения владельца 22.10.2026 (brainstorming, jira-hub#70, jira-agent#39):

• источник — журнал изменений Jira (changelog), который тянет агент: точное время и автор каждого изменения, а не разница снимков хаба;
• события ленты: смена статуса (в том числе закрытие), правка описания, новый комментарий, изменение сроков;
• регулярно — без отдельного «слепого» запроса: агент из уже выгруженных задач отбирает изменившиеся с прошлого раза (по updated) и только по ним тянет журнал;
• стартовая загрузка — только незакрытые задачи текущего спринта, не всё зеркало;
• где смотреть: MCP (спросить Claude «что изменилось за 2 часа») и, позже, веб-приложение — страница «Лента» и история в карточке задачи;
• веб-приложение в этом change не трогаем: идёт редизайн (#69), веб-часть — отдельной задачей после него.

What Changes

• Журнал изменений в хабе. Новая таблица issue_change (схема v5): одна строка — одно изменённое поле в одной записи журнала Jira (id записи, порядковый номер поля в ней, ключ задачи, время, автор, поле, было/стало). Повторно присланные записи отбрасываются по id, поэтому перекрытие окон безопасно. Время комментариев приводится к UTC (issue_comment.created_at), чтобы ленту можно было резать по времени.
• Отметка «с какого момента». Хаб при выдаче refresh дописывает параметр history: {since} — время начала последнего полного прогона, по которому журнал принят, минус запас; если такого прогона нет — {jql} стартовой загрузки (незакрытые задачи открытых спринтов из базовой JQL).
• Агент v13 (отдельный PR в jira-agent): после выгрузки состояния отбирает задачи с updated >= since и одним search с expand=changelog на 100 ключей получает их журнал; в режиме стартовой загрузки — отдельный search по history.jql. Записи отправляет хабу новым маршрутом POST /agent/history; итог — в результате refresh.
• Лента в API. GET /changes — события за период (журнал + новые комментарии), с разрезом по проекту, фильтром по видам событий и по задаче.
• MCP. Новый инструмент changes (лента за период: по умолчанию — с начала сегодняшнего дня; hours, since, until, kinds, key); issue показывает 5 последних изменений задачи.

Non-Goals

• Веб-приложение: страница «Лента», история в карточке задачи — отдельной задачей после редизайна (#69).
• Событие «задача создана» в ленте — в журнале Jira его нет; можно добавить позже по issue.created.
• Правка и удаление комментария — их нет в журнале Jira; в ленте только новые комментарии, пока они есть в Jira.
• История до стартовой загрузки по задачам вне открытых спринтов и по закрытым задачам.
• Срок хранения, чистка журнала — пока храним всё.
• Отдельный запрос журнала без refresh или своя периодичность — журнал приходит только вместе с обновлением зеркала.

Anti-Goals

• Лента молча теряет изменения: например, агент не смог дочитать журнал, а отметка «с какого момента» всё равно сдвинулась вперёд.
• Каждое автообновление тянет журнал всех задач зеркала и заметно замедляет обновление или упирается в лимиты Jira.
• Старый агент (≤ v12) или сбой чтения журнала ломает обновление зеркала.