aep/jira-agent
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(agent): ARCHITECTURE и CLAUDE.md — prune под блокировкой, нумерация ограничений; рулинги R-12, R-13 (#15)

Browse Source 
Финальное ревью I-1, M-1, M-4.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Andrey Epifancev 2026-10-14 12:55:14 +04:00
parent cd2dafe487
commit fc0f448ef8
3 changed files with 6 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
ARCHITECTURE.md
View File

@ -10,10 +10,10 @@ Jira и хаба. Спека: `../jira-hub/openspec/changes/bridge-core/`, пл
| Настройки | `load_config` | читает `agent.json`, проверяет обязательные поля | — |
| HTTP | `Http`, `HttpError`, `JiraClient`, `HubClient` | запросы; `JiraClient` считает вызовы, повторяет 429/503 по `Retry-After` (до 5 запросов, не более 4 ожиданий), хранит время последнего вызова | `urllib` |
| Папка | `FolderTransport` | транспорт `folder:` к хабу через общую папку: `req/<id>.json` → реле хаба → `resp/<id>.json`; ошибки как у `Http`; `HubClient` делегирует ему `call` (спека `jira-hub/openspec/changes/folder-transport/`) | `os`, `uuid` |
| Журнал | `Journal`, `_parse_at` | дозапись `journal.jsonl`: `started` → `finished` → `acked`; восстановление; `prune` | файловая система |
| Журнал | `Journal`, `_parse_at` | дозапись `journal.jsonl`: `started` → `finished` → `acked`; восстановление; `prune` (из CLI — под блокировкой журнала) | файловая система |
| Исполнитель | `Executor` и `do_<тип>` | по одному методу на тип команды: читает Jira, пишет только разницу; `refresh` читает и отправляет состояние в хаб | `JiraClient`, `HubClient` (только `refresh`), настройки хаба |
| Цикл | `Runner` | claim, пауза до команды, журнал, выполнение, отчёт до подтверждения, восстановление при старте | `HubClient`, `JiraClient`, `Journal`, `Executor` |
| CLI | `cmd_run`, `cmd_check`, `main` | команды `run`, `check`, `prune`; обработка сигналов | `Runner`, `Journal` |
| CLI | `cmd_run`, `cmd_check`, `cmd_prune`, `main` | команды `run`, `check`, `prune` (`run` и `prune` берут `acquire_lock` на `<журнал>.lock`); обработка сигналов | `Runner`, `Journal` |
## Границы
- Пароль и токен Jira — только в `agent.json`. В хаб, журнал и логи не попадают.
@ -28,6 +28,5 @@ Jira и хаба. Спека: `../jira-hub/openspec/changes/bridge-core/`, пл
- Тесты не ходят во внешние сервисы; фейки — `tests/fake_jira.py` и `tests/fake_hub.py`.
## Открытые вопросы
- HTTPS хаба с корпоративным CA: `HubClient` не принимает `ca_bundle`/`verify_ssl` (ограничение README, пункт 3).
- Защита `prune` от параллельной записи: блокировки нет (ограничение README, пункт 1).
- HTTPS хаба с корпоративным CA: `HubClient` не принимает `ca_bundle`/`verify_ssl` (ограничение README, пункт 2).
- Спринт задач закрытых спринтов: `sprint = null` (рулинг R-6).

2
CLAUDE.md
View File

@ -17,7 +17,7 @@
## Архитектура
- `src/agent.py` — весь агент, один файл. Разделы в порядке файла: HTTP-клиенты (`Http`, `JiraClient`, `HubClient`; `FolderTransport` — транспорт `folder:` к хабу через общую папку, ошибки как у `Http`, спека `jira-hub/openspec/specs/agent/`),
`Journal`, `Executor` (по методу `do_<тип>` на каждый тип команды), `Runner` (цикл claim → пауза → журнал →
выполнение → отчёт), CLI (`cmd_check`, `cmd_run`, `main`).
выполнение → отчёт), CLI (`cmd_check`, `cmd_run`, `cmd_prune`, `main`).
- Границы: `Executor` знает Jira, но не знает хаб (кроме `refresh`, где хаб нужен для `known_keys` и `state`).
`Runner` знает и хаб, и Jira, и журнал. Журнал не знает о Jira.
- `src/agent.example.json` — шаблон настроек, `README.md` — эксплуатация.

2
openspec/changes/bridge-hygiene/design.md
View File

@ -22,3 +22,5 @@
| Маркер | Дата | Решение | Обоснование | Цена ошибки |
|---|---|---|---|---|
| R-11 (design #21 хаба) | 2026-10-14 | Версия агента 4, `min_agent_version` не поднимается | поведение сравнения и темпа изменилось; v3 продолжает работать | нет |
| R-12 | 2026-10-14 | README: после удаления ограничения «prune без блокировки» список перенумерован, ссылки «ограничение 3» (README) и «пункт 3/пункт 1» (ARCHITECTURE.md) приведены к новой нумерации; строка «блокировки нет» снята из открытых вопросов ARCHITECTURE.md | документы не должны ссылаться на снятое ограничение (финальное ревью I-1) | неверная ссылка в документации |
| R-13 | 2026-10-14 | Ответ папки с `body: null` или без `body` считается читаемым (пустое тело), нечитаемым — только `body` иного типа | совместимость с прежним поведением (`body or ""`); реле хаба всегда пишет строку; спека уточняется: «`body` не строка и не `null`» (финальное ревью M-1) | нет: при 2xx агент получает `{}`, как раньше |