177 lines
23 KiB
Markdown
177 lines
23 KiB
Markdown
---
|
||
work_item: ORCH-009
|
||
stage: analysis
|
||
author_agent: analyst
|
||
status: ready-for-review
|
||
created_at: 2026-06-10
|
||
model_used: claude-opus-4-8
|
||
---
|
||
|
||
# 01 — BRD: ORCH-009 — Онбординг проектов в оркестратор (turnkey: Plane + репо + агенты + инфра)
|
||
|
||
Work Item: **ORCH-009** · Repo: **orchestrator** (self-hosting) · Стадия: analysis
|
||
Заказчик: Слава · Домен эпика: 📈 **D5 Масштаб (D5.2)** — `docs/epics/self-evolution.md`
|
||
|
||
> ⚠️ **Актуализация Владельца 10.06 принята как приоритетная над исходной постановкой 05.06.**
|
||
> Эталон онбординга = **сам репозиторий orchestrator** (каноны ORCH-52b/c/d/e уже кодифицированы),
|
||
> НЕ enduro-trails (устаревший пример). «Дыра: у orchestrator только deployer.md» — уже закрыта
|
||
> (в `.openclaw/agents/` полный набор 6 промптов). Скоуп — **способность** разворачивать новый
|
||
> проект по образцу орка одним проходом; онбординг конкретного нового заказчика — исполнение этой
|
||
> способности, вне данной задачи.
|
||
|
||
---
|
||
|
||
## 1. Бизнес-контекст и проблема
|
||
|
||
### 1.1. Цель
|
||
При подключении **нового** проекта к оркестратору одним проходом разворачивается всё, что нужно
|
||
мульти-агентам для автономной работы: Plane-проект (статусы/лейблы под машинные контракты),
|
||
Gitea-репо (+webhook), полный набор промптов агентов, структура документации по единым канонам,
|
||
инфра-описание (INFRA.md), регистрация в реестре проектов. Агенты нового проекта **обязаны** знать,
|
||
где лежит документация, использовать её и актуализировать.
|
||
|
||
### 1.2. Проблема сегодня
|
||
Онбординг проекта — ручная археология: шаги размазаны по докам (`SETUP_WEBHOOKS.md`,
|
||
`INFRA.md`), памяти Стрима/Славы и инцидентам (прецедент 2026-06-02: webhook всего workspace +
|
||
захардкоженный `default_repo` → задачи чужого проекта падали в enduro-trails; закрыто реестром
|
||
ORCH-6). Любой пропущенный шаг даёт **тихую деградацию**: без промптов в репо конвейер проекта не
|
||
работает вовсе; без точных имён статусов Plane ветки `Confirm Deploy`/`STOP` молча не активируются
|
||
(fail-closed); без лейблов авто-режимы и багфикс-трек молча выключены (fail-safe). Турникей-проход
|
||
обязан закрывать все слои сразу и проверяемо.
|
||
|
||
### 1.3. Установленные факты (проверено по коду, не изобретать)
|
||
|
||
| # | Факт | Где проверено |
|
||
|---|------|---------------|
|
||
| Ф-1 | Промпты агентов — **per-repo**: launcher резолвит `system_prompt: .openclaw/agents/<role>.md` относительно worktree репо задачи. Нет промптов в новом репо → конвейер для него не работает. | `src/agents/launcher.py` (реестр AGENTS, 6 ролей) |
|
||
| Ф-2 | Агент видит **только** worktree своего репо → каноны (шаблоны/стандарты) обязаны быть **скопированы** в новый репо; «ссылка на репо орка» агенту недоступна. | модель worktree `src/git_worktree.py`, launcher |
|
||
| Ф-3 | Реестр проектов строится **при импорте** из `ORCH_PROJECTS_JSON` (или built-in default): ключи `plane_project_id`/`repo`/`work_item_prefix`/`name` + опц. `agent_models`/`agent_efforts`. Регистрация нового проекта = правка `.env` на хосте + **управляемый рестарт** (операторский шаг). | `src/projects.py` (`_parse_projects_json`, `_load_projects`) |
|
||
| Ф-4 | Статусы Plane резолвятся по **точным именам** (22 ключа `_PLANE_NAME_TO_KEY`); `Confirm Deploy` (ORCH-059) и `STOP` (группа `cancelled`, ORCH-090) — **fail-closed** (нет статуса на доске → ветка не активируется); TTL-self-heal 300с (ORCH-068) — статус, добавленный позже, подхватывается без рестарта. | `src/plane_sync.py` (`_PLANE_NAME_TO_KEY`, `get_project_states`) |
|
||
| Ф-5 | Лейблы `autoApprove`/`autoDeploy` (ORCH-089) и `Bug` (ORCH-019) — **fail-safe** (нет лейбла → ручной режим / полный цикл); сопоставление по нормализованному имени через Plane API. | `src/labels.py`, `src/bug_fast_track.py`, CLAUDE.md (инфра-предусловия) |
|
||
| Ф-6 | Plane-webhook — **workspace-level** (один на все проекты, уже существует; в Plane CE создаётся SQL-ом, внешнего API нет). Gitea-webhook — **per-repo** (создаётся через API; events `push`/`pull_request`/`status`; HMAC-secret). | `docs/operations/SETUP_WEBHOOKS.md`, docstring `src/projects.py` |
|
||
| Ф-7 | Каноны (golden source) в репо орка: `docs/_templates/` — 16 скелетов (`00…18`, ORCH-52b); `docs/_standards/` — `HANDOFF_PROTOCOL.md`/`PIPELINE_DOCS.md`/`TRACEABILITY.md` (ORCH-52c/e); `.openclaw/agents/*.md` — 6 промптов канона Anthropic (ORCH-52d/92; `deployer.md` — английский **нормативно**, ADR-001 D2 ORCH-092); ADR-конвенция — `PIPELINE_DOCS.md` §4. | листинг репо, `docs/_standards/PIPELINE_DOCS.md` |
|
||
| Ф-8 | Per-repo паспорт `CLAUDE.md` — канон самого ORCH-9 (подпись в паспорте орка: «канон per-repo, см. ORCH-9»); все 6 промптов орка начинаются с «прочти CLAUDE.md». | `CLAUDE.md`, `.openclaw/agents/*.md` |
|
||
|
||
### 1.4. Принятая трактовка постановки (расхождения 05.06 ↔ 10.06)
|
||
- **Реализация в репо orchestrator** (данный конвейер пишет в этот репо; каноны живут здесь).
|
||
Упоминание отдельного репо `onboard2orch` (05.06) — историческое: его пример enduro-trails
|
||
объявлен устаревшим; судьба репо — операторское решение вне кода (рекомендация: архивировать/
|
||
оставить указатель, чтобы не плодить второй источник канона). Эскалации не требует: актуализация
|
||
10.06 прямо говорит «каноны кодифицированы в репо орка — их и брать за образец».
|
||
- **Раскладка docs/**: слой-1 постановки (05.06) указывал `docs/adr/`; канон орка —
|
||
`docs/architecture/adr/` (сквозные) + `docs/work-items/<id>/06-adr/` (per-task). Применяется
|
||
канон орка (эталон = орк).
|
||
|
||
---
|
||
|
||
## 2. Объём (scope)
|
||
|
||
### 2.1. В объёме
|
||
- **Onboarding-kit**: параметризуемый каркас нового репо — 6 промптов агентов, паспорт
|
||
`CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, `README.md`, `CHANGELOG.md`, скелет `docs/`
|
||
(включая `operations/INFRA.md`), копии `docs/_templates/` + `docs/_standards/`.
|
||
- **Onboarding-скрипт** (операторский CLI, вне конвейера): Gitea-репо + per-repo webhook,
|
||
Plane-проект + статусы + лейблы (в мере, доступной API), материализация kit (подстановка
|
||
параметров) + initial push в свежесозданный репо, генерация валидной записи реестра, режимы
|
||
dry-run / apply / verify, идемпотентность.
|
||
- **Runbook** `docs/operations/ONBOARDING.md`: полный чеклист, явная маркировка ручных шагов
|
||
(env + управляемый рестарт; UI-only действия Plane), верификация, откат.
|
||
- **Верификация способности**: автоматические структурные тесты kit (pytest) + документированный
|
||
smoke-прогон на песочнице («агент по своему промпту находит доку, использует и актуализирует»).
|
||
- **Актуализация обзорных доков** в том же PR (CLAUDE.md, `docs/architecture/README.md`,
|
||
CHANGELOG, обобщение `SETUP_WEBHOOKS.md`).
|
||
|
||
### 2.2. Вне объёма (явно, не делать)
|
||
- Исполнение онбординга конкретного нового заказчика/проекта (включая правку прод-`.env` и
|
||
рестарт прода) — операторская эксплуатация способности.
|
||
- ORCH-10 — тиражирование платформы на новый хост (IaC-bundle); мультитенантность (D5.6);
|
||
параллелизм D5.1.
|
||
- Стеки-плагины D4.1 (профили web/mobile/data/ML): kit параметризуется плейсхолдерами, без
|
||
механизма профилей.
|
||
- Любые изменения `src/**`: машина стадий, QG, launcher, реестр `projects.py` (его контракт уже
|
||
достаточен — регистрация через `ORCH_PROJECTS_JSON`), схема БД.
|
||
- Создание/миграция Plane workspace-webhook (уже существует, общий на workspace).
|
||
- Слой-3 продуктовый мониторинг онбордируемого приложения (фундамент эпика, отдельные задачи).
|
||
|
||
---
|
||
|
||
## 3. Заинтересованные стороны
|
||
- **Владелец/оператор (Слава, Стрим):** запускает онбординг, выполняет операторские шаги
|
||
(env, рестарт, UI-шаги Plane), принимает результат smoke-прогона.
|
||
- **Будущие заказчики/проекты:** получают рабочий автономный конвейер «за минуты» (D5.2).
|
||
- **Действующие проекты (enduro-trails, orchestrator):** не должны почувствовать онбординг
|
||
соседа — общий прод-инстанс, общая БД, общая очередь (self-hosting, ORCH-1).
|
||
- **Агенты конвейера:** потребители kit — промпты обязаны вести их к доке проекта.
|
||
|
||
---
|
||
|
||
## 4. Бизнес-требования (BR)
|
||
|
||
| ID | Требование | Связь |
|
||
|----|------------|-------|
|
||
| BR-1 | **Turnkey-проход:** один документированный проход (скрипт + runbook) разворачивает все слои: Plane-проект (статусы+лейблы) → Gitea-репо (+webhook) → kit в репо (initial push) → запись реестра → верификация. Список шагов закрыт и воспроизводим. | AC-1, AC-11 |
|
||
| BR-2 | **Единый эталон без форка:** kit производится от **живых** канонов репо орка — `docs/_templates/`/`docs/_standards/` копируются в новый репо в момент онбординга «как есть»; параметризация — только в kit-собственных шаблонах (промпты, паспорт, INFRA и пр.). Вторая редактируемая копия канона внутри орка не создаётся. enduro-trails эталоном не является. | AC-5, Ф-2/Ф-7 |
|
||
| BR-3 | **Полный набор промптов:** 6 ролей (analyst/architect/developer/reviewer/tester/deployer), параметризуемых под проект/стек, по канону Anthropic 52d: 5 XML-секций в нормативном порядке, запреты «❌ X → ✅ Y», `<escalation>` у developer/reviewer/tester (ORCH-092), добровольная эмиссия 6-польной frontmatter-схемы 52c, machine-verdict ключи байт-в-байт (`verdict:`/`result:`/`staging_status:`/`deploy_status:`/`security_status:`). Каждый промпт жёстко направляет: читай паспорт/`AGENTS.md`/доку ПЕРЕД работой, пиши артефакты в `docs/work-items/<id>/` по канону, обновляй CHANGELOG/доку. | AC-2, AC-4 |
|
||
| BR-4 | **Reviewer-gate на доку:** шаблон reviewer-промпта содержит проверку «документация обновлена; нет → REQUEST_CHANGES» (канон держится автоматически, не на честном слове). | AC-3 |
|
||
| BR-5 | **Каркас репо полон:** `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, `AGENTS.md` (точка входа агентов: карта доков + правила), паспорт `CLAUDE.md`, `docs/` (архитектура, конвейер, продукт-видение, `operations/`, ADR-реестр, `work-items/`, `history/`), копии `_templates/`+`_standards/`. Ссылочная целостность: промпты ссылаются только на реально существующие в каркасе пути. | AC-1, AC-5 |
|
||
| BR-6 | **INFRA.md обязателен:** топология (контейнеры/порты прод+staging/сеть/тома/БД), карта env-переменных (дескрипторы в репо, секреты только в `.env` на хосте, `.env.example` — канон), границы доступа, риски общего хоста. Для самого орка существующие self-hosting-предупреждения (общая БД/очередь/groupwide-риск рестарта) сохраняются нетронутыми. | AC-10 |
|
||
| BR-7 | **Plane-проект под машинные контракты:** статусы с **точными** каноническими именами (все 22 имени `_PLANE_NAME_TO_KEY`, включая `Confirm Deploy` и `STOP` с группой `cancelled`) + лейблы `autoApprove`/`autoDeploy`/`Bug`. Что недоступно через Plane API — явный ручной пункт runbook с командой проверки. | AC-7, Ф-4/Ф-5 |
|
||
| BR-8 | **Регистрация в реестре:** скрипт генерирует запись `ORCH_PROJECTS_JSON`, валидную через фактический парсер `projects._parse_projects_json` (round-trip). Применение env + рестарт — **операторский** шаг, явно описанный в runbook; скрипт прод-контейнер НЕ рестартит. | AC-6, AC-9, Ф-3 |
|
||
| BR-9 | **Безопасность исполнения:** dry-run по умолчанию / явный apply; идемпотентный повторный прогон (доделывает недостающее, не дублирует, ничего не удаляет); аддитивность — существующие проекты/репо не модифицируются; push — только initial в свежесозданный пустой репо (никогда в `main` существующих). | AC-8, AC-9 |
|
||
| BR-10 | **Верификация способности:** (а) автоматические структурные тесты kit/скрипта (pytest, без сети); (б) verify-режим: registry-валидность, резолв статусов, наличие webhook, полнота kit; (в) документированный smoke на песочнице: новый агент по своему промпту находит доку, использует и актуализирует её. | AC-12, AC-13 |
|
||
| BR-11 | **Прозрачность:** каждый шаг скрипта логируется; итоговый отчёт «создано / уже было (пропущено) / требует ручного шага». | AC-8 |
|
||
|
||
---
|
||
|
||
## 5. Нефункциональные требования (NFR)
|
||
|
||
| ID | Требование |
|
||
|----|------------|
|
||
| NFR-1 | **`src/**` не меняется.** Изменение — docs/templates/scripts/tests-only. `STAGE_TRANSITIONS`, реестр `QG_CHECKS`, `check_*`, machine-verdict ключи, схема БД, контракт `projects.py` — байт-в-байт. |
|
||
| NFR-2 | **Self-hosting безопасность:** скрипт никогда не рестартит/не останавливает прод-контейнер, не пишет в общую БД, не пушит в `main` существующих репо, не трогает чужие Plane-проекты/Gitea-репо. Онбординг соседа не влияет на enduro/orchestrator. |
|
||
| NFR-3 | **Секреты:** токены Plane/Gitea — только из env на хосте; сгенерированные секреты (webhook HMAC) выводятся оператору для `.env` и в гит не попадают; `.env.example` — канон. |
|
||
| NFR-4 | **Anti-drift:** структурные тесты канона для kit-промптов (аналог `tests/test_agent_prompts_canon.py`) — расхождение kit с каноном 52d ловится CI, а не глазами. |
|
||
| NFR-5 | **Оффлайн-тестируемость:** все тесты детерминированы, без реальных вызовов Plane/Gitea (моки); сетевые шаги изолированы за тонким слоем. |
|
||
| NFR-6 | **Документация = golden source:** CLAUDE.md / `docs/architecture/README.md` / CHANGELOG обновлены в том же PR; reviewer-gate применим к самому PR. |
|
||
|
||
---
|
||
|
||
## 6. Допущения и ограничения
|
||
- Plane API v1 позволяет создавать проект/статусы/лейблы (issue-API уже используется кодом);
|
||
если на практике какой-то вызов недоступен в CE — шаг деградирует в ручной пункт runbook
|
||
(fail-safe постановки, не блокер задачи).
|
||
- Скрипт — операторский инструмент: запускается человеком на хосте с токенами из `.env`,
|
||
**вне** конвейера задач; конвейер его не вызывает.
|
||
- Регистрация проекта вступает в силу после операторского рестарта (Ф-3) — это сознательное
|
||
ограничение (никакой автоматики рестартов, NFR-2); TTL-self-heal статусов (Ф-4) рестарта
|
||
не требует.
|
||
- Песочница для smoke — staging-контур (8501, изолированная БД, sandbox-проект) либо одноразовый
|
||
sandbox-проект в Plane/Gitea; выбор фиксирует архитектор/оператор в runbook.
|
||
- Языковая политика kit-промптов: по канону орка (5 ru + deployer en, ADR-001 D2 ORCH-092);
|
||
окончательное слово за архитектором, отступление — только с обоснованием в ADR.
|
||
|
||
---
|
||
|
||
## 7. Критерии успеха (резюме; детали — 03-acceptance-criteria.md)
|
||
- Kit полон и канон-чист (структурные тесты зелёные): 6 промптов 52d + reviewer-gate + каркас
|
||
репо + INFRA.md + копии канонов.
|
||
- Скрипт: dry-run печатает полный план без мутаций; apply идемпотентен; registry-запись проходит
|
||
round-trip через фактический парсер; план Plane содержит точные имена статусов и лейблы.
|
||
- Runbook закрывает 100% шагов (ручные — помечены) и верификацию.
|
||
- `src/**` не тронут; пайплайн-инварианты байт-в-байт.
|
||
- Smoke на песочнице: агент по промпту находит и актуализирует доку (документированный прогон).
|
||
|
||
---
|
||
|
||
## 8. Риски (кратко; детали — 10-tech-risks.md, заполняет архитектор)
|
||
- **R-1 Drift канона:** копия канонов в kit/новых репо разъезжается с живым каноном орка →
|
||
митигируется BR-2 (live-copy в момент онбординга) + NFR-4 (структурные тесты).
|
||
- **R-2 Тихая деградация Plane-контрактов:** опечатка в имени статуса/лейбла → fail-closed/
|
||
fail-safe ветки молча не работают → митигируется BR-7 (точные имена из кода) + verify-режимом.
|
||
- **R-3 Скрипт с боевыми токенами:** ошибка = разрушительное действие → dry-run по умолчанию,
|
||
никаких delete-операций, аддитивность (BR-9).
|
||
- **R-4 «Скрипт сделал — оператор не знает про env+restart»:** проект создан, но невидим для
|
||
оркестратора → runbook явно фиксирует операторские шаги + verify-режим показывает разрыв (BR-8/10).
|
||
- **R-5 Утечка орк-специфики в kit:** новый проект получает чужие литералы (ORCH-, порты 8500/8501,
|
||
self-hosting-правила) → структурный тест на остаточные плейсхолдеры/литералы (AC-5).
|