sdlc-hub/openspec/specs/modules/spec.md

modules Specification

Purpose

Устройство хаба из ядра и подключаемых модулей (первый — jira): что принадлежит ядру, как модуль подключается описанием, проверка пересечений при старте и единая схема базы.

Requirements

Requirement: Ядро и модули хаба

Хаб SHALL состоять из ядра и подключаемых модулей. Ядро SHALL владеть базой и миграциями, настройками хаба, проектами (метка, название), хранилищем файлов, реле общей папки, релизом агента, очередью пакетов команд, HTTP-сервером с авторизацией, раздачей веб-приложения и общим слоем MCP. Модуль SHALL подключаться к ядру описанием: таблицы, типы команд и их обработчики в очереди, маршруты HTTP, ключи настроек, фоновые работы, инструменты MCP, подкоманды CLI. Первый модуль — jira (зеркало задач, журнал изменений, вложения, команды Jira). Ядро MUST NOT импортировать модули, кроме списка подключённых модулей и истории миграций схемы.

При старте хаб SHALL проверять, что типы команд, ключи настроек и маршруты (метод и шаблон адреса) ядра и модулей не пересекаются; пересечение — ошибка старта с указанием конфликта.

Схема базы SHALL оставаться одной, с одной версией setting.schema_version на весь хаб; таблицы модуля входят в неё.

Scenario: Конфликт типов команд

• WHEN два подключённых модуля объявляют тип команды refresh
• THEN хаб не стартует, ошибка называет тип и оба модуля

Scenario: Поведение без изменений

• WHEN хаб после перестройки стартует на базе v6 с агентом v14
• THEN схема остаётся v6, копия базы не создаётся; адреса API, веба, ответы и инструменты MCP — прежние; агент берёт команды и отчитывается как раньше

Requirement: Агенты модулей

У каждого подключённого модуля, объявляющего типы команд, SHALL быть свой агент; имя агента — имя модуля (jira — jira-agent, wiki — eva-agent). Агент SHALL определяться по токену: setting.tokens = {client, agents: {<модуль>: <токен>}}, недостающий токен агента хаб создаёт при старте. Хаб SHALL для каждого агента отдельно:

• выдавать в claim только команды типов его модуля, с одной командой в полёте на агента (агенты работают параллельно);
• хранить строку agent_status (ключ — имя агента);
• держать опубликованный релиз release/<модуль>/ и состояние самообновления;
• отдавать в GET /agent/settings ключи ядра и ключи для агента только своего модуля;
• пускать на маршруты модуля со scope agent только агента этого модуля (токен другого агента — 401).

Миграция v7 SHALL сохранить прежний агентский токен как токен агента jira, перенести строку agent_status в агента jira и прежнюю публикацию release/agent.py в release/jira/. jira-agent v14 SHALL работать без обновления.

Scenario: jira-agent после выкатки

• WHEN хаб v6 с агентским токеном T и публикацией v14 обновлён до v7, jira-agent v14 шлёт claim с токеном T
• THEN 200; ответ содержит agent_release {version: 14, …}; GET /agent показывает агента jira с версией 14

Scenario: Агенты не берут чужие команды

• WHEN в очереди пакет 1 с ensure_issue и пакет 2 с wiki_sync, оба queued; агент wiki шлёт claim
• THEN выдан wiki_sync; следующий claim агента jira получает ensure_issue, хотя wiki_sync ещё claimed

Scenario: Чужой маршрут агента

• WHEN токеном агента wiki вызван POST /agent/state
• THEN 401, зеркало не меняется

Scenario: Настройки только своего модуля

• WHEN токеном агента wiki вызван GET /agent/settings
• THEN в ответе есть wiki_pacing и settings_version, ключей jira (project_key, link_types) нет

Requirement: Поля проекта от модулей

Проект ядра SHALL состоять из label, name, created_at; остальные поля проекта SHALL объявлять модули: имя, тип, проверку, изменяемость после создания, подпись и подсказку. Модуль SHALL сам хранить свои поля и отдавать их значения (включая вычисляемые) для списка проектов. При старте хаб SHALL отвергать два модуля с одним именем поля или поле модуля с именем поля ядра — ошибка старта с именем поля и модулей. В ядре SHALL NOT оставаться знания о полях модулей (доска, число задач, корень вики).

Scenario: Конфликт полей

• WHEN два модуля объявляют поле проекта root
• THEN хаб не стартует, ошибка называет поле и оба модуля

Scenario: Поля jira прежние

• WHEN после миграции v7 вызван GET /projects
• THEN у AWPCA board_id = 4216, board_type = scrum, issues_count — как до миграции

Requirement: Подготовка отчёта команды модулем

Контракт CommandHooks SHALL содержать два необязательных хука. before_result(conn, cmd, status, result, files_dir) SHALL вызываться ядром при отчёте по выданной команде до транзакции отчёта, чтобы модуль готовил тяжёлую работу (перевод, запись файлов) вне блокировки базы; ValueError из него SHALL отдаваться как ошибка сервера, а не как неверный статус отчёта. abort_result(conn, cmd) SHALL вызываться, когда отчёт не дошёл до after_result (ранний выход, исключение), и снимать подготовку before_result. Модуль без этих хуков SHALL работать как прежде.

Scenario: Подготовка до транзакции

• WHEN агент шлёт отчёт done по команде типа модуля с before_result
• THEN before_result вызван до BEGIN IMMEDIATE, после фиксации транзакции — after_result

Scenario: Отчёт прерван

• WHEN before_result выполнен, а транзакция отчёта завершилась исключением
• THEN вызван abort_result, подготовка снята, команда остаётся выданной