enduro-trails/docs/work-items/ET-015/01-brd.md

# BRD — ET-015 / ORCH-6: Multi-repo support для оркестратора

Work Item ID: ET-015
Plane title: [ORCH-6] Multi-repo: оркестратор работает по нескольким проектам
Целевой репозиторий изменений: `orchestrator` (а не `enduro-trails`)
Где трекается work item: `enduro-trails/docs/work-items/ET-015/` (организационная задача)

## 1. Контекст и проблема

Multi-Agent Orchestrator (FastAPI-сервис на порту 8500) сегодня жёстко
завязан на один проект — `enduro-trails`. Это видно по нескольким местам:

1. `ORCH_DEFAULT_REPO=enduro-trails` — единственный fallback, который
   используется почти везде в `webhooks/plane.py`, `webhooks/gitea.py`,
   `agents/launcher.py`.
2. Префикс work item ID жёстко `ET-` (`get_next_work_item_id` в `db.py`,
   строка ~93–99): любой новый таск, откуда бы он ни пришёл, получает
   ID вида `ET-NNN`.
3. Plane-настройки одиночные: `ORCH_PLANE_WORKSPACE_SLUG`,
   `ORCH_PLANE_PROJECT_ID`, словарь `PLANE_STATES` со state-id'ами
   конкретного проекта `enduro-trails`. Webhooks от другого Plane-проекта
   будут обработаны, но patch'и состояний и комментарии полетят в чужой
   проект.
4. Документация (`docs/phases/PH-1..PH-9`, фазы roadmap), agent-prompts
   (`.openclaw/agents/*.md`) и Quality Gates конвенции живут в `enduro-trails`
   и неявно считаются «универсальными».

В результате невозможно подключить к оркестратору ни сам `orchestrator` (мета-разработка),
ни любой будущий проект (например `enduro-tiles-data`, `enduro-mobile`).

## 2. Бизнес-цель

Дать оркестратору возможность обслуживать **N проектов одновременно**, не теряя
текущей функциональности по `enduro-trails` и без миграции исторических данных.

Это нужно, чтобы:

- запускать пайплайн на самом репо `orchestrator` (dogfooding —
  улучшения оркестратора проходят через тот же пайплайн);
- начать вести новые проекты той же командой и тем же инструментарием
  (тайлы, мобильное приложение, бэкенды для соседних идей);
- иметь единую точку наблюдения за разработкой нескольких репо
  (один `/status`, один Telegram-канал, одни логи).

## 3. Целевые пользователи и сценарии

| Роль | Сценарий | Ожидание |
|------|----------|----------|
| Owner (homenet542@gmail.com) | Подключить к оркестратору новый проект `foo` | За один шаг (правка конфига + перезапуск) проект становится известен оркестратору. Никаких code-change'ей в `src/`. |
| Stakeholder в Plane | Создаёт work item в проекте `Foo` (Plane workspace) | Получает branch `feature/FOO-NNN-slug` в Gitea-репо `foo`, артефакты в `docs/work-items/FOO-NNN/`, анализ запускается автоматически. |
| Developer (claude-bot) | Анализирует work item, который пришёл из проекта `Foo` | Видит корректный work item ID (`FOO-007`), корректный repo (`foo`), корректную ветку (`feature/FOO-007-...`). Worktree создаётся под нужным репо. |
| Owner | Смотрит `/status` оркестратора | Видит все активные задачи across all repos, с указанием repo для каждой. |
| Owner | Хочет временно поставить проект на паузу | Может выключить конкретный проект в конфиге, не трогая остальные. |

## 4. Бизнес-требования

### BR-1. Реестр проектов
Оркестратор должен знать список обслуживаемых проектов. Источник истины
конфигурируется (env / file / иной способ — на усмотрение архитектора).
Для каждого проекта задаются как минимум:
- имя Gitea-репо (`repo`),
- префикс work item ID (`ET`, `ORCH`, `FOO`, ...),
- идентификаторы Plane (workspace_slug, project_id),
- маппинг состояний Plane (`backlog`, `todo`, `in_progress`,
  `needs_input`, `in_review`, `blocked`, `done`, `cancelled`) — каждый
  Plane-проект имеет собственные UUID состояний.

### BR-2. Маршрутизация Plane-вебхуков по проектам
При получении вебхука от Plane оркестратор обязан определить, какому
проекту из реестра принадлежит событие (по `project_id` в payload),
и работать с настройками этого проекта (Plane state IDs, workspace,
gitea-репо).

### BR-3. Маршрутизация Gitea-вебхуков по репозиториям
При получении push / PR / status оркестратор должен использовать
`repository.name` из payload как ключ для поиска проекта в реестре
вместо `settings.default_repo`.

### BR-4. Префикс work item ID — per-project
Генерация следующего ID должна продолжать существующую нумерацию
**в пределах своего префикса**: для `enduro-trails` — `ET-016` после
`ET-015`; для `orchestrator` — `ORCH-001` для первого таска, `ORCH-002`
далее; ID одного проекта не пересекают и не сдвигают ID другого.

### BR-5. Изоляция worktree per (repo, branch)
Текущая схема `/repos/_wt/<repo>/<safe-branch>` уже репо-aware, но
оркестратор должен предполагать наличие main-clone'а для каждого репо
в `/repos/<repo>`. Если main-clone отсутствует — внятная ошибка
в логах + Telegram (а не падение).

### BR-6. Agent prompts и фазы — per-repo
Agent-промпты (`.openclaw/agents/<agent>.md`), `CLAUDE.md`, `docs/phases/`
у каждого проекта могут отличаться. Оркестратор не должен «протаскивать»
артефакты `enduro-trails` в другие репозитории.

### BR-7. Обратная совместимость
Существующий проект `enduro-trails` после миграции продолжает работать
без потери истории:
- активные задачи в `tasks` таблице не ломаются;
- ID `ET-015`, `ET-016`, … продолжают выдаваться;
- комментарии и состояния в Plane продолжают летать в текущий
  workspace/project.

### BR-8. Наблюдаемость
`/status` (и любые админ-эндпоинты) выводит `repo` для каждой активной
задачи. Telegram-уведомления и логи также включают `repo`,
чтобы их можно было разделить per-project.

### BR-9. Минимально необходимый рантайм-конфиг
Подключение нового проекта не требует изменения кода `src/`.
Только конфиг + наличие main-clone'а репозитория на хосте + перезапуск
контейнера. Webhook secret-ы (Plane / Gitea) — также per-project.

### BR-10. Безопасность
Каждый Plane-проект может иметь собственный webhook secret;
оркестратор должен проверять HMAC с правильным секретом для конкретного
проекта, иначе вебхук отбрасывается с 401.

## 5. Out of scope для этой задачи

- Параллельная обработка нескольких задач (S-4 уже сделал worktree per
  branch, но in-process очередь задач — отдельный F-2b).
- Веб-UI для управления проектами.
- Автоматическое подтягивание main-clone'а нового репо (`git clone`
  выполняется руками или другим инструментом).
- Изменение pipeline-stage машины (`stages.py`).
- Изменение модели данных Plane (state-id'ы определяются в Plane,
  оркестратор только подхватывает).

## 6. Допущения и ограничения

- Все обслуживаемые репозитории живут в одном Gitea-инстансе
  (один `ORCH_GITEA_URL`, один `ORCH_GITEA_TOKEN`, один `owner=admin`).
  Multi-Gitea — не в скоупе.
- Все Plane-проекты — в одном Plane-инстансе (`ORCH_PLANE_API_URL`),
  но могут быть в разных workspace.
- Claude CLI бинарник один и тот же (`/opt/claude-code/bin/claude.exe`).
- Hooks деплоя per-repo не обязаны существовать на этом этапе:
  если у репо нет деплой-стадии — `deploy` помечается `done` без
  смоук-теста (либо проект явно объявляет, что у него нет deploy).

## 7. Метрики успеха

1. Создание work item'а в Plane-проекте `Orchestrator` приводит к появлению
   ветки `feature/ORCH-NNN-…` в Gitea-репо `orchestrator` и запуску
   analyst-агента в worktree `/repos/_wt/orchestrator/<branch>`.
2. ID нового таска в `orchestrator` имеет префикс `ORCH-`, а не `ET-`.
3. Создание work item в `enduro-trails` продолжает работать: ID `ET-016`,
   ветка `feature/ET-016-...`, всё как раньше.
4. `/status` возвращает поле `repo` для каждой задачи.
5. Telegram-уведомление содержит `repo` в префиксе сообщения.
6. Регрессии не наблюдаются на 2 последовательных `ET-NNN` задачах
   после раскатки.

## 8. Зависимости и риски (на уровне бизнеса)

- Plane state IDs другого проекта надо получить вручную (через Plane UI
  или API) — этим занимается Owner перед подключением.
- Webhook secret per-project потребует пересоздать webhook'и
  в каждом Plane-проекте и каждом Gitea-репо.
- Schema `tasks` уже хранит `repo` — миграции данных не требуется.

## 9. Связанные документы

- 02-trz.md — функциональные/нефункциональные требования (этот пакет).
- 03-acceptance-criteria.md — критерии приёмки.
- 04-test-plan.yaml — план тестов.
- Architecture phase: создаст ADR по способу хранения реестра проектов
  и стратегии маппинга Plane state IDs.