diff --git a/CLAUDE.md b/CLAUDE.md index c731cfb..a28d36c 100644 --- a/CLAUDE.md +++ b/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). diff --git a/openspec/changes/bridge-hygiene/.openspec.yaml b/openspec/changes/archive/2026-10-14-bridge-hygiene/.openspec.yaml similarity index 100% rename from openspec/changes/bridge-hygiene/.openspec.yaml rename to openspec/changes/archive/2026-10-14-bridge-hygiene/.openspec.yaml diff --git a/openspec/changes/bridge-hygiene/design.md b/openspec/changes/archive/2026-10-14-bridge-hygiene/design.md similarity index 100% rename from openspec/changes/bridge-hygiene/design.md rename to openspec/changes/archive/2026-10-14-bridge-hygiene/design.md diff --git a/openspec/changes/bridge-hygiene/proposal.md b/openspec/changes/archive/2026-10-14-bridge-hygiene/proposal.md similarity index 100% rename from openspec/changes/bridge-hygiene/proposal.md rename to openspec/changes/archive/2026-10-14-bridge-hygiene/proposal.md diff --git a/openspec/changes/bridge-hygiene/specs/agent/spec.md b/openspec/changes/archive/2026-10-14-bridge-hygiene/specs/agent/spec.md similarity index 100% rename from openspec/changes/bridge-hygiene/specs/agent/spec.md rename to openspec/changes/archive/2026-10-14-bridge-hygiene/specs/agent/spec.md diff --git a/openspec/changes/bridge-hygiene/specs/commands/spec.md b/openspec/changes/archive/2026-10-14-bridge-hygiene/specs/commands/spec.md similarity index 100% rename from openspec/changes/bridge-hygiene/specs/commands/spec.md rename to openspec/changes/archive/2026-10-14-bridge-hygiene/specs/commands/spec.md diff --git a/openspec/changes/bridge-hygiene/specs/data-model/spec.md b/openspec/changes/archive/2026-10-14-bridge-hygiene/specs/data-model/spec.md similarity index 100% rename from openspec/changes/bridge-hygiene/specs/data-model/spec.md rename to openspec/changes/archive/2026-10-14-bridge-hygiene/specs/data-model/spec.md diff --git a/openspec/changes/bridge-hygiene/specs/hub-api/spec.md b/openspec/changes/archive/2026-10-14-bridge-hygiene/specs/hub-api/spec.md similarity index 100% rename from openspec/changes/bridge-hygiene/specs/hub-api/spec.md rename to openspec/changes/archive/2026-10-14-bridge-hygiene/specs/hub-api/spec.md diff --git a/openspec/changes/bridge-hygiene/specs/mcp/spec.md b/openspec/changes/archive/2026-10-14-bridge-hygiene/specs/mcp/spec.md similarity index 100% rename from openspec/changes/bridge-hygiene/specs/mcp/spec.md rename to openspec/changes/archive/2026-10-14-bridge-hygiene/specs/mcp/spec.md diff --git a/openspec/changes/bridge-hygiene/specs/migration/spec.md b/openspec/changes/archive/2026-10-14-bridge-hygiene/specs/migration/spec.md similarity index 100% rename from openspec/changes/bridge-hygiene/specs/migration/spec.md rename to openspec/changes/archive/2026-10-14-bridge-hygiene/specs/migration/spec.md diff --git a/openspec/specs/agent/spec.md b/openspec/specs/agent/spec.md index 2e1caaf..c79fc01 100644 --- a/openspec/specs/agent/spec.md +++ b/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` в журнале (если оно не в будущем); при пустом -журнале паузы перед первой командой нет. На HTTP 429 и 503 агент SHALL ждать `Retry-After` (иначе 60 с × номер попытки) -и повторять тот же запрос до 5 раз, считая попытки в `rate_limited`; после 5 неудач — `failed`. Пауза между записями -внутри одной команды — по зазору типа команды. +старте агент SHALL принять за время последнего вызова Jira самое позднее `at` в журнале; если оно в будущем (часы +сдвинулись назад) — текущий момент (пауза перед первой командой — полная `pause_seconds`); при пустом журнале паузы +перед первой командой нет. Оценка из журнала служит только паузе: в `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 — с восстановлением темпа после перезапуска и блокировкой одного процесса) и в каждом отчёте; -хаб предупреждает в `agent_status`, если версия ниже минимальной из настроек. +`prune` (только при остановленном агенте, иначе откажет). Версия агента SHALL быть в константе файла (4 — со сравнением +текстов без различия переводов строк и уточнённым восстановлением темпа) и в каждом отчёте; хаб предупреждает в +`agent_status`, если версия ниже минимальной из настроек. #### Scenario: Устаревший агент - **WHEN** агент версии 1 выходит на связь, а в настройках `min_agent_version = 2` @@ -99,8 +116,9 @@ README агента SHALL описывать: копирование `agent.py` 45 с) через временный файл с именем на точку и переименование, затем опрашивать `resp/.json` каждые 0,1 с. Полученный ответ агент SHALL удалить; `status` 2xx — вернуть разобранное тело, иной — выбросить `HttpError(status, body)` так же, как HTTP-клиент. Если к `deadline` ответа нет, агент SHALL удалить свой `req/.json` (если он ещё там) и -выбросить `ConnectionError`. Нечитаемый JSON ответа SHALL перечитываться до 2 с, затем `ConnectionError`. Чужие файлы -в `resp/` агент MUST NOT трогать. Цикл выполнения, журнал, повторы отчёта и восстановление SHALL работать без изменений. +выбросить `ConnectionError`. Нечитаемый ответ — не JSON-объект, `status` не целое число или `body` не строка и не `null` (`null` и отсутствие — пустое тело) — SHALL +перечитываться до 2 с, затем `ConnectionError`. Чужие файлы в `resp/` агент MUST NOT трогать. Цикл выполнения, журнал, +повторы отчёта и восстановление SHALL работать без изменений. #### Scenario: Ответ хаба через папку - **WHEN** агент вызвал `settings`, реле положило `resp/.json` со `status = 200` @@ -114,3 +132,8 @@ README агента SHALL описывать: копирование `agent.py` #### Scenario: Код ошибки хаба через папку - **WHEN** агент отправил `result` по команде, которой в хабе нет, реле положило ответ со `status = 404` - **THEN** агент получает `HttpError(404)` и считает команду закрытой, как по HTTP + +#### Scenario: Ответ с неверными типами +- **WHEN** в `resp/.json` лежит `{"id": …, "status": "ok", "body": 5}` +- **THEN** агент выбрасывает `ConnectionError` («нечитаемый ответ»), процесс не падает; цикл повторяет вызов как при + недоступном хабе diff --git a/openspec/specs/commands/spec.md b/openspec/specs/commands/spec.md index 6396958..9c34f26 100644 --- a/openspec/specs/commands/spec.md +++ b/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`). Пакет с двумя и более -`ensure_issue` с одинаковой `summary` (после обрезки пробелов по краям) SHALL отвергаться (422). Очередь SHALL выдавать -команды в порядке `(batch.created_at, seq)`, одну в полёте. Пакет и его `queued` команды MAY быть отменены; `claimed` -команда MUST NOT отменяться автоматически. +и добавить в хвост `refresh` по всем ключам пакета (кроме пакетов, состоящих только из `refresh`). Хаб SHALL проверять +типы параметров: текстовые параметры и ключи — строки (`null` у необязательного параметра — «не задан»; агент +трактует его по контракту типа, для `ensure_fields` — очистка поля), `target` команды +`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` — статус равен последнему diff --git a/openspec/specs/data-model/spec.md b/openspec/specs/data-model/spec.md index 1e927e3..af64569 100644 --- a/openspec/specs/data-model/spec.md +++ b/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 выполняться в одной транзакции; перед ней -хаб SHALL скопировать файл базы в `backups/<дата-время>-schema-v<старая>.sqlite` рядом с базой. Денежных и дробных -полей нет; даты — ISO-8601 строки в UTC, кроме `duedate` и плановых дат (даты без времени). +в `setting.schema_version` (текущая — 2). Миграция существующей базы SHALL выполняться в одной транзакции с блокировкой +записи; в той же транзакции, после повторной проверки версии, хаб SHALL скопировать файл базы в +`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:`), `fact_status`, `work_kind`, `done_text`, `rest_text`, `owner_note`, `updated_at`, `updated_by`. Обновление зеркала -MUST NOT менять `issue_note`. При завершении `ensure_issue` с временным ключом хаб SHALL переименовать строку заметок -на настоящий ключ — в том числе по позднему отчёту `done` с ключом о команде, отменённой до отчёта. +MUST NOT менять `issue_note`. При завершении `ensure_issue` с временным ключом хаб SHALL перенести заметку на настоящий +ключ — в том числе по позднему отчёту `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` -(число 429/503), `pause_seconds` (выданная пауза), `depends_on` (id команды, чей результат подставляется). Статус пакета -SHALL вычисляться из команд, не храниться. +`deliveries` (сколько раз команда выдана агенту), `finished_at`, `result` (JSON), `error` (до 1500 символов), `jira_calls`, +`rate_limited` (число 429/503), `pause_seconds` (выданная пауза), `depends_on` (id команды, чей результат подставляется). +Статус пакета 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 -хранить `last_seen_at`, `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`). +`issues_count`, `links_count`, `jira_calls`, `rate_limited`, `command_id`. При повторной выдаче команды `refresh` хаб +SHALL обнулить `issues_count` и `links_count` её `sync_run` (`started_at` не меняется); при переводе `refresh` в `failed` +по пределу выдач — проставить `finished_at`. Таблица `agent_status` (одна строка) SHALL хранить `last_seen_at`, +`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` -(увеличивается при любой правке), `backup_keep`, `auto_refresh_minutes`, `relay_dir` (абсолютный путь папки реле или -`null`, по умолчанию `null`; относительный путь и не-строка при записи — 422; агенту не передаётся). Начальные значения -SHALL импортироваться из `admin/jira-sync/config.example.json` командой `jira-hub init`; пароль и логин Jira в настройках -MUST NOT присутствовать. +`transitions_map`, `pacing`, `board_id`, `tokens` (агентский и клиентский), `settings_version` (увеличивается при любой +правке), `backup_keep`, `auto_refresh_minutes`, `relay_dir` (абсолютный путь папки реле или `null`, по умолчанию `null`; +относительный путь и не-строка при записи — 422; агенту не передаётся). Спринты агент читает с доски `board_id`, +отдельной настройки имён спринтов нет. Начальные значения SHALL импортироваться из `admin/jira-sync/config.example.json` +командой `jira-hub init`; пароль и логин Jira в настройках MUST NOT присутствовать. #### Scenario: Правка настроек поднимает версию - **WHEN** через API изменён `pacing` diff --git a/openspec/specs/hub-api/spec.md b/openspec/specs/hub-api/spec.md index 0dd448c..d53c792 100644 --- a/openspec/specs/hub-api/spec.md +++ b/openspec/specs/hub-api/spec.md @@ -9,26 +9,34 @@ HTTP API хаба `jira-hub serve`: маршруты агента (выдача `jira-hub serve` SHALL запускать один процесс: HTTP на `0.0.0.0:` (по умолчанию 8790), база и настройки в `~/.local/share/jira-hub/` (переопределяется `JIRA_HUB_HOME`). Все маршруты SHALL требовать `Authorization: Bearer `: агентский токен открывает только `/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`. - Если есть команда в `claimed`, `claim` SHALL выдать её снова (повторная выдача, см. `commands`), а не следующую из - очереди. + {id, type, params, pause_seconds}, settings_version}` или `{command: null, settings_version}`; обновляет `agent_status` + (`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` - переносится на ключ). Отчёт по команде в `queued` SHALL отвергаться 409 `not_claimed`. + `ensure_issue` в `cancelled` или `failed` без результата (результат записывается, статус не меняется, заметка `new:N` + переносится на ключ). Отчёт по команде в `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` (сравнение после - обрезки пробелов по краям; в ответе перечислены повторяющиеся темы). -- `GET /batches?limit=`, `GET /batches/{id}` (с командами), `POST /batches/{id}/cancel`. + параметрах (в том числе неверного типа значения), временном ключе без `ensure_issue`, двух и более `ensure_issue` с + одинаковой `summary` (сравнение после обрезки пробелов по краям; в ответе перечислены повторяющиеся темы). +- `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/<дата-время>-.sqlite` и хранить последние `backup_keep` копий. @@ -84,8 +111,9 @@ HTTP API хаба `jira-hub serve`: маршруты агента (выдача - **THEN** самые старые удаляются до `backup_keep` ### Requirement: Автообновление зеркала -Если `auto_refresh_minutes > 0`, агент на связи и очередь пуста дольше этого интервала, хаб SHALL поставить пакет -«Автообновление» из `refresh {jql: base_jql}`. Очередь не пуста, если есть команды в `queued` или `claimed`. +Если `auto_refresh_minutes > 0` и агент на связи, хаб SHALL поставить пакет «Автообновление» из `refresh {jql: base_jql}`, +когда в очереди нет команд в `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/.json` и обрабатывать каждый взятый запрос в отдельном потоке; - запрос с истёкшим `deadline` SHALL выбрасываться без ответа; `POST /agent/claim` SHALL пересылаться, только если до `deadline` осталось не меньше 35 с, иначе выбрасываться без ответа; -- остальные запросы реле SHALL пересылать в свой HTTP на `127.0.0.1:` тем же методом, путём и телом, с заголовком - `Authorization` из файла, и записывать ответ `resp/.json` = `{id, status, body}` (тело — строка ответа HTTP) через - временный файл с именем на точку и переименование; затем удалять `work/.json`; -- если соединение с `127.0.0.1:` не удалось, ответ SHALL иметь `status = 502` и текст ошибки в `body`; +- остальные запросы реле SHALL пересылать в свой HTTP на `:` процесса `serve` (`127.0.0.1`, если `serve` + слушает `0.0.0.0`) тем же методом, путём и телом, с заголовком `Authorization` из файла, и записывать ответ + `resp/.json` = `{id, status, body}` (тело — строка ответа HTTP) через временный файл с именем на точку и + переименование; затем удалять `work/.json`; +- если соединение со своим HTTP не удалось или ответ нарушает протокол HTTP, ответ SHALL иметь `status = 502` и текст + ошибки в `body`; - нечитаемый JSON запроса SHALL перечитываться до 2 с, затем запрос выбрасывается с записью в лог. -При старте реле SHALL удалить файлы из `work/` с записью в лог. Раз в минуту реле SHALL удалять ответы в `resp/` старше -10 мин, запросы в `req/` с `deadline` старше 60 с и файлы с именем на точку старше 10 мин. На каждый обработанный запрос -реле SHALL писать в лог хаба строку `relay <секунды>`. HTTP API, обработчики и проверка токенов -при этом не меняются. +При первой подготовке каждой папки после старта реле (в том числе новой папки после смены `relay_dir`) реле SHALL +удалить файлы из `work/` с записью в лог. Повторная подготовка той же папки (пропал подкаталог, не было доступа) SHALL +только создавать недостающие подкаталоги, не трогая `work/`. Раз в минуту +реле SHALL удалять ответы в `resp/` старше 10 мин, запросы в `req/` с `deadline` старше 60 с и файлы с именем на точку +старше 10 мин. На каждый обработанный запрос реле SHALL писать в лог хаба строку `relay +<секунды>`. 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/` не удалён, в логе нет «удалён незавершённый запрос» diff --git a/openspec/specs/mcp/spec.md b/openspec/specs/mcp/spec.md index 345f350..b3a2372 100644 --- a/openspec/specs/mcp/spec.md +++ b/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` | новый пакет / результат отмены | -| `refresh` | `keys` или `full`, `wait` (bool) | `sync_run` или id пакета | +| `command_retry` | `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 уже у агента и будет выполнена; остановить — …» diff --git a/openspec/specs/migration/spec.md b/openspec/specs/migration/spec.md index d0ba204..a5d9504 100644 --- a/openspec/specs/migration/spec.md +++ b/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:<номер строки>`): статус по факту, вид работы, что сделано, что -осталось, внутренние колонки. `links.csv` SHALL импортироваться как сверочный набор в отчёт импорта (ожидаемые связи -против зеркала после первого `refresh`), не как команды. Связь, которой в зеркале нет как `source→target` того же типа, -но есть как `target→source` того же типа, SHALL попадать в `reversed_links`, а не в `missing_links`. Импорт идемпотентен: -повтор обновляет заметки, не дублирует. +`issue_note` по ключу Jira: статус по факту, вид работы, что сделано, что осталось, внутренние колонки. Строки +`new_tasks.csv` без ключа SHALL получать временный ключ `new:<номер строки>`; строки `tasks.csv` и `epics.csv` без ключа +SHALL пропускаться. `links.csv` SHALL импортироваться как сверочный набор в отчёт импорта (ожидаемые связи против зеркала +после первого `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/` остаются как история без изменений.