sdlc-hub/CLAUDE.md

jira-hub

Что это

Хаб моста 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-13-bridge-reliability/).

Стек и ограничения

• Python 3.13, uv, hatchling, pytest; HTTP на stdlib (http.server), БД — SQLite (stdlib), MCP — пакет mcp (закреплён <2, рулинг R-10).
• Хаб не знает пароль Jira и не ходит в Jira: учётные данные и сеть до Jira только у агента.
• Зеркало задач пишет только mirror.apply_state по загрузке состояния от агента (POST /agent/state); правки идут командами через очередь.
• Хаб не создаёт команды сам: повтор после failed — новая команда по запросу человека/интерфейса. Команду, выданную агенту и оставшуюся без отчёта, хаб довыдаёт при следующем claim (до 3 выдач, затем failed).
• Данные: ~/.local/share/jira-hub/ (JIRA_HUB_HOME): hub.sqlite, backups/. Порт по умолчанию 8790.
• Два статических токена (в таблице setting): агентский открывает только /agent/*, клиентский — остальное.

Архитектура

• src/jira_hub/ — весь код пакета, без разделения на ядро и адаптеры; чистая логика (commands, mirror, queue, settings) принимает соединение SQLite параметром.
• db (схема, миграции) ← settings, mirror, commands ← queue ← api (HTTP, маршруты в ROUTES, фоновый tick, реле общей папки relay (поток в serve, настройка relay_dir)) ← cli.
• client (HTTP-клиент хаба) ← mcp_server (stdio, инструменты MCP); importer → mirror/settings; backup вызывается из api и из db (копия перед миграцией схемы).
• Подробная карта модулей и границ — ARCHITECTURE.md.

Команды

• uv run pytest — весь набор тестов. Зелёным считается только весь набор.
• uv sync — установка окружения.
• uv run jira-hub init --config PATH [--force] — настройки проекта из config.example.json, создание токенов.
• uv run jira-hub serve [--host] [--port] — локальный запуск хаба.
• uv run jira-hub import FOLDER — импорт CSV-пакета admin/jira-sync; uv run jira-hub mcp — MCP по stdio; uv run jira-hub tokens — показать токены.

Тесты

• Golden-тесты: tests/fixtures/<name>.* + эталон <name>.expected.*. Внешние сервисы в тестах мокаются.
• SQLite в памяти или во временном JIRA_HUB_HOME (tmp_path); API поднимается на порту 0 в отдельном потоке. Jira и агент в тестах не участвуют.

Первая подсистема

Очередь команд (queue.py, Task 5): пакеты, порядок (batch.created_at, seq), одна команда в полёте, временные ключи new:<n>, подтверждение по состоянию зеркала. Остальное (API, MCP, импорт) надстраивается над ней.

OpenSpec и superpowers

• Вход в любую задачу — superpowers:brainstorming. Skills openspec-propose и openspec-explore сами по себе не запускать.
• Когда brainstorming классифицировал задачу как architectural, структуру change создать через openspec new change <id> (или /opsx:propose <id>), а содержимое proposal.md, specs/ и design.md написать по итогам brainstorming. tasks.md из OpenSpec не заполнять — задачи живут в плане superpowers.
• /opsx:apply не использовать: исполнение идёт через writing-plans и SDD/executing-plans.
• openspec archive <id> — после merge PR, как часть чеклиста закрытия.
• Хук require-plan защищает любой каталог src/ на любой глубине. Если код лежит иначе — перечислить каталоги (префиксы от корня, по одному в строке) в .claude/code-paths.