---
work_item: ORCH-009
stage: architecture
author_agent: architect
status: proposed
created_at: 2026-06-10
model_used: 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).
