From fc0f448ef8eee2cade973a9debebdba5318cb975 Mon Sep 17 00:00:00 2001 From: Andrey Epifancev Date: Wed, 14 Oct 2026 12:55:14 +0400 Subject: [PATCH] =?UTF-8?q?docs(agent):=20ARCHITECTURE=20=D0=B8=20CLAUDE.m?= =?UTF-8?q?d=20=E2=80=94=20prune=20=D0=BF=D0=BE=D0=B4=20=D0=B1=D0=BB=D0=BE?= =?UTF-8?q?=D0=BA=D0=B8=D1=80=D0=BE=D0=B2=D0=BA=D0=BE=D0=B9,=20=D0=BD?= =?UTF-8?q?=D1=83=D0=BC=D0=B5=D1=80=D0=B0=D1=86=D0=B8=D1=8F=20=D0=BE=D0=B3?= =?UTF-8?q?=D1=80=D0=B0=D0=BD=D0=B8=D1=87=D0=B5=D0=BD=D0=B8=D0=B9;=20?= =?UTF-8?q?=D1=80=D1=83=D0=BB=D0=B8=D0=BD=D0=B3=D0=B8=20R-12,=20R-13=20(#1?= =?UTF-8?q?5)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Финальное ревью I-1, M-1, M-4. Co-Authored-By: Claude Opus 5.5 --- ARCHITECTURE.md | 7 +++---- CLAUDE.md | 2 +- openspec/changes/bridge-hygiene/design.md | 2 ++ 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index ff7f99a..8267ba8 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -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/.json` → реле хаба → `resp/.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). diff --git a/CLAUDE.md b/CLAUDE.md index f4c5629..6ea9558 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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` — эксплуатация. diff --git a/openspec/changes/bridge-hygiene/design.md b/openspec/changes/bridge-hygiene/design.md index 5d70b1f..f394a20 100644 --- a/openspec/changes/bridge-hygiene/design.md +++ b/openspec/changes/bridge-hygiene/design.md @@ -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 агент получает `{}`, как раньше |