--- 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/.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//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», `` у developer/reviewer/tester (ORCH-092), добровольная эмиссия 6-польной frontmatter-схемы 52c, machine-verdict ключи байт-в-байт (`verdict:`/`result:`/`staging_status:`/`deploy_status:`/`security_status:`). Каждый промпт жёстко направляет: читай паспорт/`AGENTS.md`/доку ПЕРЕД работой, пиши артефакты в `docs/work-items//` по канону, обновляй 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).