Merge pull request 'docs(openspec): архив bridge-hygiene (#13)' (#15) from chore/13-archive-bridge-hygiene into main

CLAUDE.md

@@ -1,7 +1,7 @@
 # jira-hub
 
 ## Что это
-Хаб моста Jira для АРМ КА: единственный источник истины по задачам проекта AURORA (метка AWPCA) на Mac mini (`192.168.0.106`). Хранит зеркало задач, служебные заметки и очередь команд в SQLite, отдаёт HTTP API в локальной сети (агенту на виртуалке `jira-agent` и интерфейсам) и MCP-сервер для Claude. Главный сценарий: из чата поставить пакет команд, агент на виртуалке выполняет их в Jira по правилу «проверь, потом сделай» и возвращает состояние задач в зеркало. Спеки: `openspec/specs/`; текущий change — `openspec/changes/bridge-hygiene/`.
+Хаб моста Jira для АРМ КА: единственный источник истины по задачам проекта AURORA (метка AWPCA) на Mac mini (`192.168.0.106`). Хранит зеркало задач, служебные заметки и очередь команд в SQLite, отдаёт HTTP API в локальной сети (агенту на виртуалке `jira-agent` и интерфейсам) и MCP-сервер для Claude. Главный сценарий: из чата поставить пакет команд, агент на виртуалке выполняет их в Jira по правилу «проверь, потом сделай» и возвращает состояние задач в зеркало. Спеки: `openspec/specs/`; текущего change нет (последний — `openspec/changes/archive/2026-10-14-bridge-hygiene/`).
 
 ## Стек и ограничения
 - Python 3.13, uv, hatchling, pytest; HTTP на stdlib (`http.server`), БД — SQLite (stdlib), MCP — пакет `mcp` (закреплён `<2`, рулинг R-10).

openspec/specs/agent/spec.md

@@ -45,7 +45,9 @@
 rate_limited, at}`, `acked {command_id, at}`. При старте агент SHALL: отправить хабу все `finished` без `acked`; для
 `claimed`/`started` без `finished` — запросить команду у хаба по id и, если она в хабе всё ещё `claimed`, выполнить её
 заново по правилу «проверь, потом сделай» с паузой `pause_seconds` из ответа хаба, не записывая `claimed` повторно.
-Команда `python3 agent.py prune` SHALL удалять из журнала записи с `acked` старше 30 дней.
+Команда `python3 agent.py prune` SHALL удалять из журнала записи с `acked` старше 30 дней; она SHALL брать ту же
+блокировку `<журнал>.lock`, что `run`, и при занятой блокировке завершаться с кодом 1 и сообщением «агент запущен»,
+не меняя журнал.
 
 #### Scenario: Падение после ответа Jira
 - **WHEN** агент упал между `POST /issue` и записью `finished`, затем перезапущен
@@ -57,12 +59,18 @@ rate_limited, at}`, `acked {command_id, at}`. При старте агент SHA
 - **THEN** в журнал дописываются `started 40`, `finished 40`, `acked 40`; второй строки `claimed 40` нет; перед выполнением
   агент выдерживает 30 с от последнего вызова Jira
 
+#### Scenario: prune при работающем агенте
+- **WHEN** `agent.py run` работает, и запущен `agent.py prune` с тем же журналом
+- **THEN** `prune` пишет «агент запущен…» и завершается с кодом 1; журнал не изменён
+
 ### Requirement: Ограничение темпа и 429
 Агент SHALL помнить время последнего вызова Jira (любого) и не начинать команду раньше `pause_seconds` после него. При
-старте агент SHALL принять за время последнего вызова Jira самое позднее `at` в журнале (если оно не в будущем); при пустом
+старте агент SHALL принять за время последнего вызова Jira самое позднее `at` в журнале; если оно в будущем (часы
-журнале паузы перед первой командой нет. На HTTP 429 и 503 агент SHALL ждать `Retry-After` (иначе 60 с × номер попытки)
+сдвинулись назад) — текущий момент (пауза перед первой командой — полная `pause_seconds`); при пустом журнале паузы
-и повторять тот же запрос до 5 раз, считая попытки в `rate_limited`; после 5 неудач — `failed`. Пауза между записями
+перед первой командой нет. Оценка из журнала служит только паузе: в `claim` агент SHALL передавать `last_jira_call_at`
-внутри одной команды — по зазору типа команды.
+только после настоящего вызова Jira в текущем процессе, до него — `null`. На HTTP 429 и 503 агент SHALL ждать
+`Retry-After` (иначе 60 с × номер попытки) и повторять тот же запрос до 5 раз, считая попытки в `rate_limited`; после
+5 неудач — `failed`. Пауза между записями внутри одной команды — по зазору типа команды.
 
 #### Scenario: 429 с Retry-After
 - **WHEN** Jira ответила 429 с `Retry-After: 90`
@@ -72,6 +80,14 @@ rate_limited, at}`, `acked {command_id, at}`. При старте агент SHA
 - **WHEN** последняя запись журнала `finished` сделана 10 с назад, агент перезапущен и получил команду с `pause_seconds = 30`
 - **THEN** агент ждёт около 20 с перед первым вызовом Jira по команде
 
+#### Scenario: Время журнала в будущем
+- **WHEN** последняя запись журнала на 2 часа позже текущего времени, агент перезапущен и получил команду с `pause_seconds = 30`
+- **THEN** агент ждёт 30 с перед первым вызовом Jira; в логе — что время журнала в будущем
+
+#### Scenario: После перезапуска хаб не получает оценку из журнала
+- **WHEN** агент перезапущен с непустым журналом и отправляет первый `claim`
+- **THEN** `last_jira_call_at` в `claim` — `null`; после первого вызова Jira следующий `claim` несёт его время
+
 ### Requirement: Чтение состояния
 `refresh` SHALL выполняться запросом `search` (`jql`, `fields` = поля зеркала включая `issuelinks` и спринт,
 `maxResults = 100`, постранично) и отправляться хабу пачками по 100 задач со связями; ключи из `issuelinks`, которых нет
@@ -85,8 +101,9 @@ rate_limited, at}`, `acked {command_id, at}`. При старте агент SHA
 ### Requirement: Доставка и запуск
 README агента SHALL описывать: копирование `agent.py` и `agent.example.json` через общую папку, заполнение `agent.json`
 (включая выбор транспорта в `hub_url`), `check`, запуск в терминале и через `nohup` с логом, опциональный launchd-plist,
-`prune`. Версия агента SHALL быть в константе файла (3 — с восстановлением темпа после перезапуска и блокировкой одного процесса) и в каждом отчёте;
+`prune` (только при остановленном агенте, иначе откажет). Версия агента SHALL быть в константе файла (4 — со сравнением
-хаб предупреждает в `agent_status`, если версия ниже минимальной из настроек.
+текстов без различия переводов строк и уточнённым восстановлением темпа) и в каждом отчёте; хаб предупреждает в
+`agent_status`, если версия ниже минимальной из настроек.
 
 #### Scenario: Устаревший агент
 - **WHEN** агент версии 1 выходит на связь, а в настройках `min_agent_version = 2`
@@ -99,8 +116,9 @@ README агента SHALL описывать: копирование `agent.py`
 45 с) через временный файл с именем на точку и переименование, затем опрашивать `resp/<id>.json` каждые 0,1 с.
 Полученный ответ агент SHALL удалить; `status` 2xx — вернуть разобранное тело, иной — выбросить `HttpError(status, body)`
 так же, как HTTP-клиент. Если к `deadline` ответа нет, агент SHALL удалить свой `req/<id>.json` (если он ещё там) и
-выбросить `ConnectionError`. Нечитаемый JSON ответа SHALL перечитываться до 2 с, затем `ConnectionError`. Чужие файлы
+выбросить `ConnectionError`. Нечитаемый ответ — не JSON-объект, `status` не целое число или `body` не строка и не `null` (`null` и отсутствие — пустое тело) — SHALL
-в `resp/` агент MUST NOT трогать. Цикл выполнения, журнал, повторы отчёта и восстановление SHALL работать без изменений.
+перечитываться до 2 с, затем `ConnectionError`. Чужие файлы в `resp/` агент MUST NOT трогать. Цикл выполнения, журнал,
+повторы отчёта и восстановление SHALL работать без изменений.
 
 #### Scenario: Ответ хаба через папку
 - **WHEN** агент вызвал `settings`, реле положило `resp/<id>.json` со `status = 200`
@@ -114,3 +132,8 @@ README агента SHALL описывать: копирование `agent.py`
 #### Scenario: Код ошибки хаба через папку
 - **WHEN** агент отправил `result` по команде, которой в хабе нет, реле положило ответ со `status = 404`
 - **THEN** агент получает `HttpError(404)` и считает команду закрытой, как по HTTP
+
+#### Scenario: Ответ с неверными типами
+- **WHEN** в `resp/<id>.json` лежит `{"id": …, "status": "ok", "body": 5}`
+- **THEN** агент выбрасывает `ConnectionError` («нечитаемый ответ»), процесс не падает; цикл повторяет вызов как при
+  недоступном хабе

openspec/specs/commands/spec.md

@@ -23,10 +23,18 @@
 Семантика `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
@@ -56,10 +64,14 @@ SHALL отвергаться при создании пакета (422).
 
 ### Requirement: Пакет и порядок выполнения
 Пакет SHALL создаваться одним вызовом с автором, заголовком и списком команд; хаб SHALL назначить `seq` по порядку списка
-и добавить в хвост `refresh` по всем ключам пакета (кроме пакетов, состоящих только из `refresh`). Пакет с двумя и более
+и добавить в хвост `refresh` по всем ключам пакета (кроме пакетов, состоящих только из `refresh`). Хаб SHALL проверять
-`ensure_issue` с одинаковой `summary` (после обрезки пробелов по краям) SHALL отвергаться (422). Очередь SHALL выдавать
+типы параметров: текстовые параметры и ключи — строки (`null` у необязательного параметра — «не задан»; агент
-команды в порядке `(batch.created_at, seq)`, одну в полёте. Пакет и его `queued` команды MAY быть отменены; `claimed`
+трактует его по контракту типа, для `ensure_fields` — очистка поля), `target` команды
-команда MUST NOT отменяться автоматически.
+`ensure_status` — строка или список строк, `labels`, `labels_add`, `labels_remove`, `keys` — списки строк, `replace` —
+логическое значение; нарушение — 422 с именем параметра. Пакет с двумя и более `ensure_issue` с одинаковой `summary`
+(после обрезки пробелов по краям) SHALL отвергаться (422). Очередь SHALL выдавать команды в порядке
+`(batch.created_at, seq)`, одну в полёте. Пакет и его `queued` команды MAY быть отменены; `claimed` команда MUST NOT
+отменяться автоматически.
 
 #### Scenario: Оценка длительности
 - **WHEN** создаётся пакет из 3 `ensure_fields` и 2 `ensure_comment`
@@ -69,6 +81,10 @@ SHALL отвергаться при создании пакета (422).
 - **WHEN** пакет содержит `ensure_issue {temp_key: new:1, summary: "Отчёт"}` и `ensure_issue {temp_key: new:2, summary: " Отчёт "}`
 - **THEN** 422 с темой «Отчёт», пакет не создан
 
+#### Scenario: Параметр не того типа
+- **WHEN** пакет содержит `ensure_fields {key: X, labels_add: "AWPCA"}`
+- **THEN** 422 с указанием `labels_add`, пакет не создан
+
 ### Requirement: Политика темпа и пауза на команде
 Хаб SHALL хранить `pacing` как минимальные зазоры в секундах по типу команды (по умолчанию: `ensure_issue` и
 `ensure_fields` 120, `ensure_comment`, `ensure_status`, `ensure_link`, `ensure_sprint` 30, `refresh` 2). При выдаче команды
@@ -81,7 +97,8 @@ SHALL выдерживать зазор типа команды между за
 - **THEN** `claim` возвращает пустой ответ, агент не спит сверх долгого запроса
 
 ### Requirement: Ошибки и подтверждение по состоянию
-Ошибка команды SHALL записываться в `error` (HTTP-код, текст Jira до 1500 символов), пакет продолжается.
+Ошибка команды SHALL записываться в `error` (HTTP-код, текст Jira); хаб SHALL хранить не больше 1500 символов `error`,
+обрезая присланное. Пакет после ошибки продолжается.
 
 **Повторная выдача.** Агент запрашивает новую команду, только когда у него нет незавершённой (см. `agent`), поэтому
 команда в `claimed` к моменту следующего `claim` считается не доставленной или потерянной агентом. При `claim` хаб SHALL
@@ -89,7 +106,9 @@ SHALL выдерживать зазор типа команды между за
 `pause_seconds` по текущей политике темпа, новый `claimed_at`, `deliveries + 1`. Если у неё уже `deliveries >= 3`, хаб SHALL
 перевести её в `failed` с `error = "агент не отчитался после 3 выдач"` и перейти к следующей (довыдача другой `claimed`
 или следующая `queued`). Довыдача — доставка той же выдачи, а не повтор команды: новых команд хаб MUST NOT создавать
-сам, повтор после `failed` — новая команда с теми же параметрами по запросу интерфейса.
+сам, повтор после `failed` — новая команда с теми же параметрами по запросу интерфейса. Если агент всё же отчитался
+`done` с ключом по `ensure_issue`, переведённой в `failed` по пределу, хаб SHALL записать ключ в результат и перенести
+заметку, не меняя статус (как для отменённой, см. `hub-api`).
 
 **Подтверждение по состоянию.** Если после любого `refresh` желаемый результат команды в `claimed` виден в зеркале, хаб
 SHALL перевести её в `confirmed_by_state`: `ensure_fields` — все поля совпадают; `ensure_status` — статус равен последнему

openspec/specs/data-model/spec.md

@@ -8,26 +8,38 @@
 ### Requirement: Схема базы хаба
 База хаба SHALL быть одним файлом SQLite (WAL) с таблицами `issue`, `issue_link`, `issue_note`, `batch`, `command`,
 `sync_run`, `agent_status`, `setting`. Схема SHALL создаваться и мигрироваться самим хабом при старте по номеру версии
-в `setting.schema_version` (текущая — 2). Миграция существующей базы SHALL выполняться в одной транзакции; перед ней
+в `setting.schema_version` (текущая — 2). Миграция существующей базы SHALL выполняться в одной транзакции с блокировкой
-хаб SHALL скопировать файл базы в `backups/<дата-время>-schema-v<старая>.sqlite` рядом с базой. Денежных и дробных
+записи; в той же транзакции, после повторной проверки версии, хаб SHALL скопировать файл базы в
-полей нет; даты — ISO-8601 строки в UTC, кроме `duedate` и плановых дат (даты без времени).
+`backups/<дата-время>-schema-v<старая>.sqlite` рядом с базой — одна копия на миграцию, сколько бы соединений ни
+открывалось одновременно. Каталог данных хаба и `backups/` SHALL иметь права `0700` (в базе токены): хаб выставляет их
+при создании и при каждом старте; если выставить не удалось — предупреждение в лог, работа продолжается. Денежных и
+дробных полей нет; даты — ISO-8601 строки в UTC, кроме `duedate` и плановых дат (даты без времени).
 
 #### Scenario: Первый запуск
 - **WHEN** хаб стартует с несуществующим файлом базы
-- **THEN** файл создаётся, таблицы и индексы на месте, `setting.schema_version` = текущая
+- **THEN** файл создаётся, таблицы и индексы на месте, `setting.schema_version` = текущая; каталог данных с правами `0700`
 
 #### Scenario: Миграция базы v1
 - **WHEN** хаб стартует с базой `schema_version = 1`, в которой есть задачи, заметки и команда в `claimed`
 - **THEN** в `backups/` копия базы v1; добавлена `command.deliveries` (у `claimed` — 1, у остальных — 0); данные на месте;
   `schema_version = 2`
 
+#### Scenario: Два соединения к базе v1
+- **WHEN** к базе `schema_version = 1` одновременно открываются два соединения
+- **THEN** миграция выполнена один раз, в `backups/` одна копия `schema-v1`
+
+#### Scenario: Открытый каталог данных
+- **WHEN** хаб стартует, каталог данных существует с правами `0755`
+- **THEN** права каталога и `backups/` — `0700`
+
 ### Requirement: Зеркало задачи
 Таблица `issue` SHALL хранить задачу Jira как есть: `key` (PK), `id`, `issue_type`, `summary`, `description` (wiki),
 `status`, `priority`, `assignee`, `reporter`, `duedate`, `planned_start`, `planned_end`, `epic_key`, `labels` (JSON-список),
 `sprint`, `jira_updated`, `fetched_at`, `neighbor` (0/1 — вне базовой JQL, дочитана по связи), `created`. Таблица `issue_link`
 SHALL хранить связи `(source_key, target_key, link_type)` с направлением по семантике Jira: `source` блокирует/ссылается
 на `target` (у `source` в GET это `outwardIssue`). Обновлять `issue` и `issue_link` SHALL только загрузка состояния от
-агента; HTTP API интерфейсов и MCP MUST NOT писать в них.
+агента; HTTP API интерфейсов и MCP MUST NOT писать в них. Полный прогон (`refresh` по базовой JQL), завершившийся
+`done`, SHALL помечать `neighbor = 1` задачи, не обновлённые им, — только если прогон загрузил хотя бы одну задачу.
 
 #### Scenario: Загрузка состояния заменяет связи
 - **WHEN** агент прислал состояние задачи X с двумя связями
@@ -38,46 +50,73 @@ SHALL хранить связи `(source_key, target_key, link_type)` с нап
 - **WHEN** в `issuelinks` задачи из базовой JQL есть ключ Y вне JQL
 - **THEN** Y сохраняется с `neighbor = 1`; при следующем полном `refresh`, если Y вошла в JQL, `neighbor = 0`
 
+#### Scenario: Пустой полный прогон
+- **WHEN** полный `refresh` завершился `done`, загрузив 0 задач
+- **THEN** признак `neighbor` задач зеркала не меняется
+
 ### Requirement: Служебные заметки
 Таблица `issue_note` SHALL хранить поля, которых нет в Jira: `key` (PK; ключ Jira или временный `new:<n>`),
 `fact_status`, `work_kind`, `done_text`, `rest_text`, `owner_note`, `updated_at`, `updated_by`. Обновление зеркала
-MUST NOT менять `issue_note`. При завершении `ensure_issue` с временным ключом хаб SHALL переименовать строку заметок
+MUST NOT менять `issue_note`. При завершении `ensure_issue` с временным ключом хаб SHALL перенести заметку на настоящий
-на настоящий ключ — в том числе по позднему отчёту `done` с ключом о команде, отменённой до отчёта.
+ключ — в том числе по позднему отчёту `done` с ключом о команде, отменённой или переведённой в `failed` до отчёта. Если
+под настоящим ключом заметка уже есть, хаб SHALL слить их: каждое поле берётся из временной заметки, если там оно
+непустое, иначе остаётся под настоящим ключом; `updated_at`/`updated_by` — от более поздней; временная строка удаляется.
 
 #### Scenario: Заметка переживает refresh
 - **WHEN** у задачи есть `issue_note.fact_status = "В работе"` и приходит полное обновление зеркала
 - **THEN** `fact_status` не изменился
 
+#### Scenario: Слияние с заметкой под ключом
+- **WHEN** у `new:5` заметка `work_kind = "Аналитика"`, `owner_note` пусто; у `AURORA-1640` заметка `owner_note = "спросить ИБ"`;
+  `ensure_issue` для `new:5` завершилась с `AURORA-1640`
+- **THEN** у `AURORA-1640` `work_kind = "Аналитика"` и `owner_note = "спросить ИБ"`; строки `new:5` нет
+
 ### Requirement: Пакеты и команды
 Таблица `batch` SHALL хранить `id`, `title`, `author`, `created_at`, `cancelled_at`, `estimate_seconds`.
 Таблица `command` SHALL хранить `id`, `batch_id`, `seq`, `type`, `params` (JSON), `status`
 (`queued | claimed | done | failed | skipped | cancelled | confirmed_by_state`), `claimed_at` (время последней выдачи),
-`deliveries` (сколько раз команда выдана агенту), `finished_at`, `result` (JSON), `error`, `jira_calls`, `rate_limited`
+`deliveries` (сколько раз команда выдана агенту), `finished_at`, `result` (JSON), `error` (до 1500 символов), `jira_calls`,
-(число 429/503), `pause_seconds` (выданная пауза), `depends_on` (id команды, чей результат подставляется). Статус пакета
+`rate_limited` (число 429/503), `pause_seconds` (выданная пауза), `depends_on` (id команды, чей результат подставляется).
-SHALL вычисляться из команд, не храниться.
+Статус пакета SHALL вычисляться из команд и `cancelled_at`, не храниться: есть команды не в терминальном статусе —
+«выполняется» (или «в очереди», если все `queued`); все терминальные и пакет отменён (`cancelled_at`) — «отменён»;
+все терминальные без отмены — «завершён».
 
 #### Scenario: Статус пакета
 - **WHEN** в пакете 3 команды: `done`, `claimed`, `queued`
 - **THEN** статус пакета «выполняется»; когда все в терминальных статусах — «завершён», с числом `failed`/`skipped`
 
+#### Scenario: Отменённый пакет с выполненной командой
+- **WHEN** в пакете команда 1 `done`, команда 2 `claimed`, команда 3 `queued`; пакет отменён, затем агент отчитался по 2
+- **THEN** статус пакета «отменён» (`cancelled`), счётчики показывают две `done` и одну `cancelled`
+
 ### Requirement: Журнал синхронизаций и статус агента
 Таблица `sync_run` SHALL хранить каждую загрузку состояния: `started_at`, `finished_at`, `kind` (`keys | jql`), `query`,
-`issues_count`, `links_count`, `jira_calls`, `rate_limited`, `command_id`. Таблица `agent_status` (одна строка) SHALL
+`issues_count`, `links_count`, `jira_calls`, `rate_limited`, `command_id`. При повторной выдаче команды `refresh` хаб
-хранить `last_seen_at`, `agent_version`, `settings_version`, `current_command_id`, `last_jira_call_at`. Через API и MCP
+SHALL обнулить `issues_count` и `links_count` её `sync_run` (`started_at` не меняется); при переводе `refresh` в `failed`
-`agent_status` SHALL отдаваться с признаком `online` (истина, если `last_seen_at` моложе 5 минут) и списком
+по пределу выдач — проставить `finished_at`. Таблица `agent_status` (одна строка) SHALL хранить `last_seen_at`,
-`redelivered` — команд в `claimed`, выданных больше одного раза (`id`, `type`, `claimed_at`, `deliveries`).
+`agent_version`, `settings_version`, `current_command_id`, `last_jira_call_at`. Через API и MCP `agent_status` SHALL
+отдаваться с признаком `online` (истина, если `last_seen_at` моложе 5 минут) и списком `redelivered` — команд в
+`claimed`, выданных больше одного раза (`id`, `type`, `claimed_at`, `deliveries`).
 
 #### Scenario: Агент давно не выходил на связь
 - **WHEN** `last_seen_at` старше 5 минут
 - **THEN** `agent_status` через API и MCP отдаётся с `online = false`
 
+#### Scenario: Довыдача refresh не удваивает счётчики
+- **WHEN** `refresh` загрузил 150 задач, отчёт потерян, команда выдана снова и загрузила те же 150
+- **THEN** у её `sync_run` `issues_count = 150`
+
+#### Scenario: refresh сдался по пределу выдач
+- **WHEN** `refresh` переведён в `failed` «агент не отчитался после 3 выдач»
+- **THEN** у его `sync_run` проставлен `finished_at`
+
 ### Requirement: Настройки
 Таблица `setting` SHALL хранить парами ключ–JSON: `base_jql`, `field_ids`, `issue_types`, `priority_map`, `link_types`,
-`transitions_map`, `pacing`, `board_id`, `sprint_names`, `tokens` (агентский и клиентский), `settings_version`
+`transitions_map`, `pacing`, `board_id`, `tokens` (агентский и клиентский), `settings_version` (увеличивается при любой
-(увеличивается при любой правке), `backup_keep`, `auto_refresh_minutes`, `relay_dir` (абсолютный путь папки реле или
+правке), `backup_keep`, `auto_refresh_minutes`, `relay_dir` (абсолютный путь папки реле или `null`, по умолчанию `null`;
-`null`, по умолчанию `null`; относительный путь и не-строка при записи — 422; агенту не передаётся). Начальные значения
+относительный путь и не-строка при записи — 422; агенту не передаётся). Спринты агент читает с доски `board_id`,
-SHALL импортироваться из `admin/jira-sync/config.example.json` командой `jira-hub init`; пароль и логин Jira в настройках
+отдельной настройки имён спринтов нет. Начальные значения SHALL импортироваться из `admin/jira-sync/config.example.json`
-MUST NOT присутствовать.
+командой `jira-hub init`; пароль и логин Jira в настройках MUST NOT присутствовать.
 
 #### Scenario: Правка настроек поднимает версию
 - **WHEN** через API изменён `pacing`

openspec/specs/hub-api/spec.md

@@ -9,26 +9,34 @@ HTTP API хаба `jira-hub serve`: маршруты агента (выдача
 `jira-hub serve` SHALL запускать один процесс: HTTP на `0.0.0.0:<port>` (по умолчанию 8790), база и настройки в
 `~/.local/share/jira-hub/` (переопределяется `JIRA_HUB_HOME`). Все маршруты SHALL требовать `Authorization: Bearer <token>`:
 агентский токен открывает только `/agent/*`, клиентский — всё остальное. Ответы — JSON, ошибки — `{error, detail}` с
-кодами 400/401/404/409/422.
+кодами 400 (неверное тело или `Content-Length`), 401, 404, 409, 413 (тело больше предела), 422, 500 (внутренняя ошибка);
+реле общей папки дополнительно отвечает 502. Методы, кроме GET, POST и PUT, отвечают 501 стандартной страницей
+`http.server`, не JSON.
 
 #### Scenario: Чужой токен
 - **WHEN** агентским токеном вызван `GET /issues`
 - **THEN** 401
 
+#### Scenario: Неподдерживаемый метод
+- **WHEN** `DELETE /issues/AURORA-1`
+- **THEN** 501, тело не JSON; база не меняется
+
 ### Requirement: Маршруты агента
 Хаб SHALL предоставлять агенту следующие маршруты (все под агентским токеном):
 - `POST /agent/claim` `{agent_version, settings_version, last_jira_call_at}` — долгий запрос до 30 с; ответ `{command:
-  {id, type, params, pause_seconds}, settings_version}` или `{command: null, settings_version}`; обновляет `agent_status`.
+  {id, type, params, pause_seconds}, settings_version}` или `{command: null, settings_version}`; обновляет `agent_status`
-  Если есть команда в `claimed`, `claim` SHALL выдать её снова (повторная выдача, см. `commands`), а не следующую из
+  (`last_jira_call_at = null` не затирает прежнее значение). Если есть команда в `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`, заметка `new:N`
+  `ensure_issue` в `cancelled` или `failed` без результата (результат записывается, статус не меняется, заметка `new:N`
-  переносится на ключ). Отчёт по команде в `queued` SHALL отвергаться 409 `not_claimed`.
+  переносится на ключ). Отчёт по команде в `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`.
+  пачками; `neighbor_keys` — ключи вне базовой JQL, дочитанные по связям; хаб обновляет зеркало и `sync_run`. Каждая
+  пачка применяется независимо; `page` и `last_page` необязательны и хабом не используются.
 - `GET /agent/known-keys` — ключи зеркала (для определения соседей).
 
 #### Scenario: Выдача с подстановкой ключа
@@ -43,17 +51,28 @@ HTTP API хаба `jira-hub serve`: маршруты агента (выдача
 - **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`
+
 ### Requirement: Маршруты интерфейсов
 Хаб SHALL предоставлять интерфейсам (MCP, позже просмотрщик) следующие маршруты под клиентским токеном:
 - `GET /issues` с фильтрами `sprint`, `assignee`, `work_kind`, `fact_status`, `status`, `label`, `epic`, `neighbor`,
-  `q` (подстрока темы), `limit`/`offset` — компактные карточки (ключ, тема, статус, приоритет, срок, исполнитель, спринт,
+  `q` (подстрока темы), `limit`/`offset` — строки зеркала (все поля `issue`) с `fact_status` и `work_kind` из заметок;
-  эпик, заметки кратко).
+  сокращение до карточки — дело интерфейса.
 - `GET /issues/{key}` — задача целиком: поля, связи в обе стороны, заметки, последние 10 команд по ней.
 - `PUT /issues/{key}/note` — заметки (частичное обновление, `updated_by` из тела).
 - `POST /batches` `{title, author, commands: [...]}` → `{id, estimate_seconds}`; 422 при неизвестном типе, неверных
-  параметрах, временном ключе без `ensure_issue`, двух и более `ensure_issue` с одинаковой `summary` (сравнение после
+  параметрах (в том числе неверного типа значения), временном ключе без `ensure_issue`, двух и более `ensure_issue` с
-  обрезки пробелов по краям; в ответе перечислены повторяющиеся темы).
+  одинаковой `summary` (сравнение после обрезки пробелов по краям; в ответе перечислены повторяющиеся темы).
-- `GET /batches?limit=`, `GET /batches/{id}` (с командами), `POST /batches/{id}/cancel`.
+- `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`.
@@ -75,6 +94,14 @@ HTTP API хаба `jira-hub serve`: маршруты агента (выдача
 - **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`
+
 ### Requirement: Резервные копии
 Перед выдачей первой команды пакета, содержащего записи в Jira, хаб SHALL скопировать файл базы в `backups/<дата-время>-<batch>.sqlite`
 и хранить последние `backup_keep` копий.
@@ -84,8 +111,9 @@ HTTP API хаба `jira-hub serve`: маршруты агента (выдача
 - **THEN** самые старые удаляются до `backup_keep`
 
 ### Requirement: Автообновление зеркала
-Если `auto_refresh_minutes > 0`, агент на связи и очередь пуста дольше этого интервала, хаб SHALL поставить пакет
+Если `auto_refresh_minutes > 0` и агент на связи, хаб SHALL поставить пакет «Автообновление» из `refresh {jql: base_jql}`,
-«Автообновление» из `refresh {jql: base_jql}`. Очередь не пуста, если есть команды в `queued` или `claimed`.
+когда в очереди нет команд в `queued` и `claimed` и последний `sync_run` начат раньше, чем `auto_refresh_minutes` назад
+(или `sync_run` ещё нет).
 
 #### Scenario: Очередь занята
 - **WHEN** интервал прошёл, но в очереди есть `queued` команды
@@ -95,6 +123,10 @@ HTTP API хаба `jira-hub serve`: маршруты агента (выдача
 - **WHEN** интервал прошёл, `queued` нет, одна команда в `claimed`
 - **THEN** автообновление не ставится; команда довыдаётся при следующем `claim`
 
+#### Scenario: Недавнее обновление
+- **WHEN** очередь пуста, `auto_refresh_minutes = 60`, последний `sync_run` начат 20 минут назад
+- **THEN** автообновление не ставится
+
 ### Requirement: Реле через общую папку
 `jira-hub serve` SHALL запускать поток реле вместе с HTTP-сервером. Пока настройка `relay_dir` пуста (`null`), реле
 бездействует; настройку оно SHALL перечитывать не реже раза в 5 с, включение и выключение не требуют перезапуска. Если
@@ -107,16 +139,20 @@ HTTP API хаба `jira-hub serve`: маршруты агента (выдача
 - реле SHALL брать запрос переименованием в `work/<id>.json` и обрабатывать каждый взятый запрос в отдельном потоке;
 - запрос с истёкшим `deadline` SHALL выбрасываться без ответа; `POST /agent/claim` SHALL пересылаться, только если до
   `deadline` осталось не меньше 35 с, иначе выбрасываться без ответа;
-- остальные запросы реле SHALL пересылать в свой HTTP на `127.0.0.1:<port>` тем же методом, путём и телом, с заголовком
+- остальные запросы реле SHALL пересылать в свой HTTP на `<host>:<port>` процесса `serve` (`127.0.0.1`, если `serve`
-  `Authorization` из файла, и записывать ответ `resp/<id>.json` = `{id, status, body}` (тело — строка ответа HTTP) через
+  слушает `0.0.0.0`) тем же методом, путём и телом, с заголовком `Authorization` из файла, и записывать ответ
-  временный файл с именем на точку и переименование; затем удалять `work/<id>.json`;
+  `resp/<id>.json` = `{id, status, body}` (тело — строка ответа HTTP) через временный файл с именем на точку и
-- если соединение с `127.0.0.1:<port>` не удалось, ответ SHALL иметь `status = 502` и текст ошибки в `body`;
+  переименование; затем удалять `work/<id>.json`;
+- если соединение со своим HTTP не удалось или ответ нарушает протокол HTTP, ответ SHALL иметь `status = 502` и текст
+  ошибки в `body`;
 - нечитаемый JSON запроса SHALL перечитываться до 2 с, затем запрос выбрасывается с записью в лог.
 
-При старте реле SHALL удалить файлы из `work/` с записью в лог. Раз в минуту реле SHALL удалять ответы в `resp/` старше
+При первой подготовке каждой папки после старта реле (в том числе новой папки после смены `relay_dir`) реле SHALL
-10 мин, запросы в `req/` с `deadline` старше 60 с и файлы с именем на точку старше 10 мин. На каждый обработанный запрос
+удалить файлы из `work/` с записью в лог. Повторная подготовка той же папки (пропал подкаталог, не было доступа) SHALL
-реле SHALL писать в лог хаба строку `relay <METHOD> <path> <status> <секунды>`. HTTP API, обработчики и проверка токенов
+только создавать недостающие подкаталоги, не трогая `work/`. Раз в минуту
-при этом не меняются.
+реле SHALL удалять ответы в `resp/` старше 10 мин, запросы в `req/` с `deadline` старше 60 с и файлы с именем на точку
+старше 10 мин. На каждый обработанный запрос реле SHALL писать в лог хаба строку `relay <METHOD> <path> <status>
+<секунды>`. HTTP API, обработчики и проверка токенов при этом не меняются.
 
 #### Scenario: Запрос через папку
 - **WHEN** в `req/` появился `a1.json` с `GET /agent/settings`, агентским токеном и `deadline` через 60 с
@@ -137,3 +173,11 @@ HTTP API хаба `jira-hub serve`: маршруты агента (выдача
 #### Scenario: Папка не подключена
 - **WHEN** `relay_dir` задан, но каталога нет; через минуту каталог появился
 - **THEN** в логе одно предупреждение; после появления каталога реле создаёт подкаталоги и обрабатывает запросы
+
+#### Scenario: Сбой протокола своего HTTP
+- **WHEN** при пересылке запроса свой HTTP оборвал ответ (`http.client.HTTPException`)
+- **THEN** в `resp/` ответ со `status = 502` и текстом ошибки; реле продолжает работу
+
+#### Scenario: Повторная подготовка не трогает взятые запросы
+- **WHEN** реле работает, в `work/` лежит взятый запрос, и пропал подкаталог `resp/`
+- **THEN** реле создаёт `resp/` заново; файл в `work/` не удалён, в логе нет «удалён незавершённый запрос»

openspec/specs/mcp/spec.md

@@ -24,12 +24,16 @@ MCP-сервер хаба (`jira-hub mcp`, stdio) для Claude: инструм
 | `batch_status` | `id` | статусы команд, ошибки, оценка остатка |
 | `batch_wait` | `id`, `timeout_minutes` (≤ 60) | как `batch_status`, возвращается по завершении или по таймауту |
 | `batches` | `limit` | последние пакеты со статусом |
-| `command_retry`, `batch_cancel` | `id` | новый пакет / результат отмены |
+| `command_retry` | `id` | новый пакет |
-| `refresh` | `keys` или `full`, `wait` (bool) | `sync_run` или 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 за сутки, версия настроек |
 | `sync_log` | `limit` | последние `sync_run` |
 | `settings_get`, `settings_set` | ключ, значение | текущее значение / новая `settings_version` |
 
+Описание инструмента `batch_create` SHALL предупреждать, что `ensure_issue` должна нести `labels` с базовой меткой
+проекта (`AWPCA`): хаб и агент метки сами не добавляют, и задача без неё выпадает из базовой JQL и из зеркала.
+
 Автор команд из MCP SHALL быть `claude`; из API без автора — `api`.
 
 #### Scenario: Пакет из чата
@@ -43,3 +47,7 @@ MCP-сервер хаба (`jira-hub mcp`, stdio) для Claude: инструм
 #### Scenario: Статус агента с довыдачей
 - **WHEN** агент на связи, команда 40 выдана дважды и ещё без отчёта
 - **THEN** ответ `agent_status` содержит «агент онлайн» и строку о команде 40 с числом выдач 2
+
+#### Scenario: Отмена пакета с командой у агента
+- **WHEN** `batch_cancel {id: 9}`, команда 30 пакета в `claimed`
+- **THEN** ответ содержит вид пакета и строку «команда #30 уже у агента и будет выполнена; остановить — …»

openspec/specs/migration/spec.md

@@ -18,11 +18,12 @@ MUST NOT переноситься (они у агента).
 
 ### Requirement: Импорт CSV-пакета
 `jira-hub import <папка admin/jira-sync>` SHALL прочитать `tasks.csv`, `new_tasks.csv`, `epics.csv` и заполнить
-`issue_note` (ключ Jira; для строк без ключа — `new:<номер строки>`): статус по факту, вид работы, что сделано, что
+`issue_note` по ключу Jira: статус по факту, вид работы, что сделано, что осталось, внутренние колонки. Строки
-осталось, внутренние колонки. `links.csv` SHALL импортироваться как сверочный набор в отчёт импорта (ожидаемые связи
+`new_tasks.csv` без ключа SHALL получать временный ключ `new:<номер строки>`; строки `tasks.csv` и `epics.csv` без ключа
-против зеркала после первого `refresh`), не как команды. Связь, которой в зеркале нет как `source→target` того же типа,
+SHALL пропускаться. `links.csv` SHALL импортироваться как сверочный набор в отчёт импорта (ожидаемые связи против зеркала
-но есть как `target→source` того же типа, SHALL попадать в `reversed_links`, а не в `missing_links`. Импорт идемпотентен:
+после первого `refresh`), не как команды. Связь, которой в зеркале нет как `source→target` того же типа, но есть как
-повтор обновляет заметки, не дублирует.
+`target→source` того же типа, SHALL попадать в `reversed_links`, а не в `missing_links`. Импорт идемпотентен: повтор
+обновляет заметки, не дублирует.
 
 #### Scenario: Импорт и первая синхронизация
 - **WHEN** выполнены `init`, `import`, запущены хаб и агент, `refresh full` завершён
@@ -34,6 +35,10 @@ MUST NOT переноситься (они у агента).
   1446→1445
 - **THEN** связь в `reversed_links`, в `missing_links` её нет
 
+#### Scenario: Эпик без ключа
+- **WHEN** в `epics.csv` строка без значения в колонке «Ключ»
+- **THEN** строка пропущена, заметка `new:*` для неё не создаётся
+
 ### Requirement: Что остаётся в admin/
 После ввода моста `admin/jira-sync/README.md` SHALL получить в начале пометку «заменено мостом jira-hub/jira-agent,
 CSV заморожены <дата>»; `jira_sync.py`, CSV, `runs/`, `summary.md`, `_generator/` остаются как история без изменений.