Files

claude-bot 11551572e9 analyst(ET): auto-commit from analyst run_id=584

2026-06-10 16:08:43 +03:00

23 KiB

Raw Blame History

work_item, stage, author_agent, status, created_at, model_used

work_item	stage	author_agent	status	created_at	model_used
ORCH-009	analysis	analyst	ready-for-review	2026-06-10	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).

23 KiB Raw Blame History Unescape Escape