feat(onboarding): turnkey project onboarding — kit + CLI + runbook (ORCH-009) #120

Merged

admin merged 13 commits from feature/ORCH-009-turnkey-plane into main 2026-06-10 19:50:38 +03:00

Conversation 0 Commits 13 Files Changed 47 +5460 -12

admin commented 2026-06-10 15:34:47 +03:00

Owner

Copy Link

ORCH-009 — Turnkey-онбординг проектов

Операторская способность развернуть новый проект одним проходом: Plane-проект (22 статуса с точными именами + лейблы) → Gitea-репо (+per-repo webhook) → каркас репо (kit) + initial push → запись реестра → верификация. Реализовано вне рантайма и вне конвейера.

Состав

• Kit onboarding/repo-skeleton/ — параметризуемый каркас нового репо: 6 промптов канона 52d/92 (5 ru + deployer en, рамка shared-host-гардрейлов), reviewer-gate на доку, паспорт CLAUDE.md, AGENTS.md, CONTRIBUTING.md, скелет docs/ с обязательным operations/INFRA.md, .env.example. Плейсхолдеры {{NAME}} + stdlib-рендер; словарь onboarding/placeholders.json (биекция словарь↔kit — тестом). Канон не форкается: _templates/_standards live-copy в момент материализации (BR-2/D3).
• CLI scripts/onboard_project.py — plan (дефолт, GET-only, ноль мутаций) / apply (идемпотентный ensure, без delete) / verify. Закрытый список read-only импортов src (ADR D4); группы статусов по ADR D5 (STOP→cancelled; терминальные — только Done/Cancelled/STOP); webhook переиспользует глобальный ORCH_GITEA_WEBHOOK_SECRET (TR-6); initial push только в свежесозданный пустой репо (INV-4 не затронут); прод не рестартится, .env не правится, ничего не удаляется (NFR-2); Plane CE API-пробел → manual-step (fail-safe).
• Runbook docs/operations/ONBOARDING.md + обобщённый SETUP_WEBHOOKS.md; CLAUDE.md / docs/architecture/README.md / CHANGELOG — в том же PR.
• Тесты: test_onboarding_kit.py / test_onboarding_script.py (моки, без сети) / test_onboarding_invariants.py (снапшоты STAGE_TRANSITIONS/QG_CHECKS, закрытый список импортов, эталонные .openclaw/agents/ не тронуты) — 83 теста, TC-01…TC-21.

Инварианты

• src/** — 0 строк диффа (NFR-1/AC-12); эталонные промпты орка не тронуты.
• Полный регресс: 1713 passed (TC-22); ruff чист на файлах задачи.

⚠️ Флаг размера (правило developer-промпта)

PR > 1500 строк. Осознанно НЕ дроблю: объём — преимущественно инертный markdown (kit-шаблоны ~1.9k + номерные доки стадий analysis/architecture ~1.2k + runbook); исполняемого кода ~1.1k (операторский CLI вне горячих путей) + ~1.1k тестов. Скоуп «kit+CLI+runbook одной способностью» зафиксирован BRD/ТЗ/ADR (D1–D11) на стадиях анализа/архитектуры; дробление дало бы нетестируемые фрагменты (kit без CLI, CLI без kit). Рантайм-риск нулевой по построению. На будущее урок принят: способности такого объёма декомпозировать на уровне задач.

AC-13 (операторский smoke)

Выполняется вручную по runbook на staging-контуре (8501) после мержа; протокол — раздел «Журнал smoke-прогонов» ONBOARDING.md (ADR D8).

Refs: ORCH-009

🤖 Generated with Claude Code

## ORCH-009 — Turnkey-онбординг проектов Операторская способность развернуть **новый** проект одним проходом: Plane-проект (22 статуса с точными именами + лейблы) → Gitea-репо (+per-repo webhook) → каркас репо (kit) + initial push → запись реестра → верификация. Реализовано **вне рантайма и вне конвейера**. ### Состав - **Kit `onboarding/repo-skeleton/`** — параметризуемый каркас нового репо: 6 промптов канона 52d/92 (5 ru + deployer en, рамка shared-host-гардрейлов), reviewer-gate на доку, паспорт `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, скелет `docs/` с обязательным `operations/INFRA.md`, `.env.example`. Плейсхолдеры `{{NAME}}` + stdlib-рендер; словарь `onboarding/placeholders.json` (биекция словарь↔kit — тестом). Канон **не форкается**: `_templates`/`_standards` live-copy в момент материализации (BR-2/D3). - **CLI `scripts/onboard_project.py`** — `plan` (дефолт, GET-only, ноль мутаций) / `apply` (идемпотентный ensure, без delete) / `verify`. Закрытый список read-only импортов `src` (ADR D4); группы статусов по ADR D5 (`STOP`→`cancelled`; терминальные — только Done/Cancelled/STOP); webhook переиспользует глобальный `ORCH_GITEA_WEBHOOK_SECRET` (TR-6); initial push **только** в свежесозданный пустой репо (INV-4 не затронут); прод не рестартится, `.env` не правится, ничего не удаляется (NFR-2); Plane CE API-пробел → `manual-step` (fail-safe). - **Runbook `docs/operations/ONBOARDING.md`** + обобщённый `SETUP_WEBHOOKS.md`; CLAUDE.md / `docs/architecture/README.md` / CHANGELOG — в том же PR. - **Тесты:** `test_onboarding_kit.py` / `test_onboarding_script.py` (моки, без сети) / `test_onboarding_invariants.py` (снапшоты `STAGE_TRANSITIONS`/`QG_CHECKS`, закрытый список импортов, эталонные `.openclaw/agents/` не тронуты) — 83 теста, TC-01…TC-21. ### Инварианты - `src/**` — **0 строк диффа** (NFR-1/AC-12); эталонные промпты орка не тронуты. - Полный регресс: **1713 passed** (TC-22); ruff чист на файлах задачи. ### ⚠️ Флаг размера (правило developer-промпта) PR > 1500 строк. Осознанно НЕ дроблю: объём — преимущественно инертный markdown (kit-шаблоны ~1.9k + номерные доки стадий analysis/architecture ~1.2k + runbook); исполняемого кода ~1.1k (операторский CLI вне горячих путей) + ~1.1k тестов. Скоуп «kit+CLI+runbook одной способностью» зафиксирован BRD/ТЗ/ADR (D1–D11) на стадиях анализа/архитектуры; дробление дало бы нетестируемые фрагменты (kit без CLI, CLI без kit). Рантайм-риск нулевой по построению. На будущее урок принят: способности такого объёма декомпозировать на уровне задач. ### AC-13 (операторский smoke) Выполняется вручную по runbook на staging-контуре (8501) после мержа; протокол — раздел «Журнал smoke-прогонов» `ONBOARDING.md` (ADR D8). Refs: ORCH-009 🤖 Generated with [Claude Code](https://claude.com/claude-code)

admin changed title from feat: ORCH-009-turnkey-plane to feat(onboarding): turnkey project onboarding — kit + CLI + runbook (ORCH-009) 2026-06-10 15:44:31 +03:00

admin added 8 commits 2026-06-10 16:08:45 +03:00

docs: init ORCH-009 business request 1289d728a8

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

architect(ET): auto-commit from architect run_id=585 ed04f71fd1

architect(ET): auto-commit from architect run_id=586 d141280390

developer(ET): auto-commit from developer run_id=587 13e9618bd2

feat(onboarding): turnkey project onboarding — kit + CLI + runbook (ORCH-009) ... dc1cb87818

Operator capability to bring a NEW project online in one pass, fully
outside the runtime and the pipeline (src/** byte-exact, no kill-switch
needed — activation is an explicit human CLI run). Reference = the
orchestrator repo itself (ORCH-52b/c/d/e canons).

* onboarding/repo-skeleton/ — parametrized kit of a new repo: 6 agent
  prompt templates per canon 52d/92 (5 ru + deployer en with the
  shared-host guardrail frame), reviewer doc-gate (REQUEST_CHANGES),
  CLAUDE.md passport, AGENTS.md, CONTRIBUTING.md, docs/ skeleton with
  mandatory operations/INFRA.md, .env.example; {{NAME}} placeholders +
  stdlib render, dictionary onboarding/placeholders.json (bijection
  held by tests). Canon is NOT forked: docs/_templates + docs/_standards
  are live-copied from the checkout at materialization time (BR-2/D3).
* scripts/onboard_project.py — plan (default, GET-only, zero mutations)
  / apply (idempotent ensure, no delete ops at all) / verify (registry
  round-trip via the actual projects._parse_projects_json, all 22 state
  names incl. fail-closed Confirm Deploy/STOP, labels, webhook, kit
  completeness, unresolved-placeholder scan). Closed read-only src
  import list (ADR D4); state groups fixed per ADR D5 (STOP→cancelled,
  terminal groups only Done/Cancelled/STOP); Gitea webhook reuses the
  single global ORCH_GITEA_WEBHOOK_SECRET (TR-6); initial push ONLY
  into a freshly created empty repo (INV-4 untouched); never restarts
  prod / never edits .env / deletes nothing (NFR-2); secrets masked
  (NFR-3); Plane CE API gaps degrade to manual-step (fail-safe).
* docs/operations/ONBOARDING.md runbook + SETUP_WEBHOOKS.md generalized
  per-repo; CLAUDE.md / docs/architecture/README.md / CHANGELOG.md
  updated in the same PR (golden source).
* Anti-drift tests: test_onboarding_kit.py / test_onboarding_script.py
  (mocked, no network) / test_onboarding_invariants.py (snapshots of
  STAGE_TRANSITIONS/QG_CHECKS, closed CLI import list, reference
  .openclaw/agents/ prompts untouched). Full regression: 1713 passed.

Refs: ORCH-009

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

reviewer(ET): auto-commit from reviewer run_id=589 cc3ed42041

tester(ET): auto-commit from tester run_id=590 dd09e3da89

admin force-pushed feature/ORCH-009-turnkey-plane from f4b055e76a to dd09e3da89 2026-06-10 16:08:45 +03:00 Compare

admin added 1 commit 2026-06-10 16:17:57 +03:00

fix(tests): hermetic ORCH-41 model/effort tests vs host env (unblock merge-gate) ... e9038182a1

Merge-gate re-test runs under the orchestrator's prod env, where the
operator legitimately set ORCH_AGENT_FALLBACK_MODEL and changed
ORCH_AGENT_MODEL_DEFAULT / ORCH_AGENT_EFFORT_*. Two ORCH-41-era tests
asserted SHIPPED defaults through the env-backed settings singleton and
failed 3/3 there, while Gitea CI (clean env) stayed green. Branch
ORCH-009 touches neither src/ nor these tests - latent non-hermetic
landmine on main, detonated by the prod env change.

- test_resolve_agent_effort.py: autouse fixture now mirrors the sibling
  model-file baseline (pins shipped model/fallback fields) so the
  flag-assembly tests are env-independent.
- test_resolve_agent_model.py: fixture also resets agent_fallback_model;
  test_fallback_model_disabled_by_default now asserts the CLASS field
  default (the actual ORCH-074 ADR-001 G4 invariant: shipped default
  is ""), never-break is_valid_model asserts unchanged byte-for-byte.

Clean-env behaviour is byte-equivalent (fixtures pin exactly what an
empty env yields). Full suite: 1713 passed (was 2 failed / 1711).

Refs: ORCH-009

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

admin added 1 commit 2026-06-10 16:18:30 +03:00

developer(ET): auto-commit from developer run_id=592 b26a391fa3

admin added 1 commit 2026-06-10 17:26:46 +03:00

reviewer(ET): auto-commit from reviewer run_id=593 b97ffae7a1

admin added 1 commit 2026-06-10 19:40:52 +03:00

tester(ET): auto-commit from tester run_id=600 e5c3774bc5

admin merged commit 4c232112d4 into main 2026-06-10 19:50:38 +03:00

admin referenced this issue from a commit 2026-06-10 19:50:40 +03:00

Merge pull request 'feat(onboarding): turnkey project onboarding — kit + CLI + runbook (ORCH-009)' (#120) from feature/ORCH-009-turnkey-plane into main

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

No items

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

admin

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: admin/orchestrator#120