orchestrator/docs/architecture/adr/adr-0035-turnkey-project-onboarding.md

work_item, stage, author_agent, status, created_at, model_used

work_item	stage	author_agent	status	created_at	model_used
ORCH-009	architecture	architect	proposed	2026-06-10	claude-opus-4-8

adr-0035: Turnkey-онбординг проектов — kit + операторский CLI + runbook (ORCH-009)

Статус

Proposed

Контекст

Подключение нового проекта к оркестратору — ручная археология по разрозненным докам и памяти; каждый пропущенный шаг даёт тихую деградацию: без промптов в репо конвейер проекта не работает вовсе (launcher резолвит .openclaw/agents/<role>.md относительно worktree репо задачи); без точных имён статусов Plane ветки Confirm Deploy (ORCH-059) / STOP (ORCH-090) молча не активируются (fail-closed); без лейблов autoApprove/autoDeploy/Bug авто-режимы (ORCH-089) и багфикс-трек (ORCH-019) молча выключены (fail-safe). Эталон онбординга — сам репозиторий orchestrator (каноны ORCH-52b/c/d/e кодифицированы в docs/_templates/, docs/_standards/, .openclaw/agents/). Домен D5.2 эпика саморазвития: способность разворачивать новый проект одним проходом.

Решение

Способность реализуется вне рантайма и вне конвейера — src/** байт-в-байт не меняется (STAGE_TRANSITIONS/QG_CHECKS/check_*/machine-verdict/схема БД/контракт projects.py нетронуты), kill-switch не нужен (активация — только явный запуск операторского CLI):

1. Onboarding-kit onboarding/repo-skeleton/ — параметризуемый каркас нового репо: 6 промптов агентов канона 52d/92 (5 XML-секций, «❌→✅», эмиссия схемы 52c, verdict-ключи байт-в-байт; язык — канон орка: 5 ru + deployer en), паспорт CLAUDE.md, AGENTS.md (точка входа агентов), CONTRIBUTING.md, README.md, CHANGELOG.md, скелет docs/ с обязательным operations/INFRA.md, .env.example. Плейсхолдеры {{NAME}} + stdlib-рендер (без новых pip-зависимостей); словарь — onboarding/placeholders.json (биекция со вхождениями в kit держится тестами). Канон не форкается: docs/_templates/ + docs/_standards/ НЕ хранятся в kit — копируются live из чекаута орка в момент материализации.
2. Операторский CLI scripts/onboard_project.py — plan (дефолт, GET-only, ни одной мутации) / apply (идемпотентный ensure, без delete-операций) / verify. Шаги: Plane-проект → 22 статуса с точными именами из plane_sync._PLANE_NAME_TO_KEY (read-only импорт — нулевой дрейф; канонические группы фиксированы: STOP→cancelled, терминальные группы только у Done/Cancelled/STOP — иначе terminal-detection ORCH-068 ложно терминалит) → лейблы → Gitea-репо (+per-repo webhook push/pull_request/status; HMAC-секрет переиспользуется из ORCH_GITEA_WEBHOOK_SECRET — приёмник один на все репо) → материализация kit + initial push только в свежесозданный пустой репо (INV-4 не затрагивается) → merged-вывод ORCH_PROJECTS_JSON, провалидированный фактическим projects._parse_projects_json (round-trip). Недоступное в Plane CE API → manual-step со ссылкой на runbook (fail-safe). Скрипт никогда не рестартит прод, не правит .env, не пушит в существующие репо, ничего не удаляет.
3. Runbook docs/operations/ONBOARDING.md — полный чеклист: предусловия (токены) → скрипт → операторские шаги (env + управляемый рестарт с self-hosting-предупреждением; UI-only Plane) → верификация (verify + smoke) → откат. Smoke-контур — staging (8501, изолированная БД) + одноразовый sandbox-проект (SMK); протокол — «Журнал smoke-прогонов» в runbook.

Анти-дрейф — структурные тесты kit (аналог tests/test_agent_prompts_canon.py) + снапшот-тест STAGE_TRANSITIONS/QG_CHECKS (контроль ненарушения src). Branch protection main новых репо не включается (ломала бы PR-merge API merge-актора — ложные HOLD класса ORCH-093).

Последствия

• + Новый проект разворачивается одним проходом проверяемо: все слои (Plane-контракты, webhook, промпты, дока, реестр) закрыты скриптом+runbook; тихие деградации ловит verify.
• + Нулевой риск рантайма: изменение docs/templates/scripts/tests-only; регресс enduro/orchestrator невозможен по построению; общая БД не читается и не пишется скриптом.
• + Единый эталон без форка: новые репо получают живой канон момента онбординга; обновления канона в них едут обычными PR с reviewer-gate.
• − Регистрация в реестре остаётся операторской (env + управляемый рестарт — Ф-3, сознательное ограничение NFR-2); разрыв «создано, но не зарегистрировано» виден через verify.
• − Закрытый список read-only импортов из src (projects._parse_projects_json, plane_sync._PLANE_NAME_TO_KEY, поля config.settings) — связь с приватными именами; поломка при рефакторинге видимая (тесты), расширение списка — только через ADR.
• Ограничение: способность ≠ исполнение: онбординг конкретного заказчика — операторская эксплуатация (вне ORCH-009); тиражирование на новый хост — ORCH-10 (вне объёма).

Детально: docs/work-items/ORCH-009/06-adr/ADR-001-turnkey-onboarding-kit-and-cli.md (D1…D11 — раскладка, плейсхолдеры, copy-vs-template split, импорт src, группы статусов, webhook-секрет, формат реестра, smoke-контур, языковая политика, branch protection, форма CLI).