228 lines
21 KiB
Markdown
228 lines
21 KiB
Markdown
---
|
||
work_item: ORCH-009
|
||
stage: analysis
|
||
author_agent: analyst
|
||
status: ready-for-review
|
||
created_at: 2026-06-10
|
||
model_used: claude-opus-4-8
|
||
---
|
||
|
||
# 02 — ТЗ (TRZ): ORCH-009 — Онбординг проектов в оркестратор (turnkey)
|
||
|
||
Work Item: **ORCH-009** · Repo: **orchestrator** · Стадия: analysis
|
||
|
||
> ТЗ описывает **что** должно измениться и **где** (модули/контракты/артефакты). **Как** (точная
|
||
> раскладка kit, механизм подстановки, формат CLI) — решает архитектор в `06-adr/`. Имена путей
|
||
> ниже — рабочее предложение; архитектор вправе скорректировать, сохранив требования и AC.
|
||
|
||
> ⚠️ Скоуп по актуализации 10.06: эталон = репо orchestrator; deliverables — в этом репо.
|
||
> `src/**` НЕ меняется (NFR-1) — задача docs/templates/scripts/tests-only.
|
||
|
||
---
|
||
|
||
## 1. Сводка изменения
|
||
Создать **способность turnkey-онбординга** нового проекта: (1) параметризуемый **onboarding-kit**
|
||
(каркас нового репо: 6 промптов агентов по канону 52d/92, паспорт, AGENTS/CONTRIBUTING, скелет
|
||
`docs/` с INFRA.md, копии живых канонов `_templates/`+`_standards/`); (2) операторский
|
||
**onboarding-скрипт** (Gitea-репо + per-repo webhook; Plane-проект + статусы + лейблы;
|
||
материализация kit + initial push; генерация записи реестра; dry-run/apply/verify; идемпотентно);
|
||
(3) **runbook** `docs/operations/ONBOARDING.md` (полный чеклист, ручные шаги, верификация);
|
||
(4) **структурные тесты** анти-дрейфа. Конвейер/движок не трогаются.
|
||
|
||
---
|
||
|
||
## 2. Задействованные модули / пути
|
||
|
||
| Путь | Действие | Роль |
|
||
|------|----------|------|
|
||
| `onboarding/repo-skeleton/**` | создать | параметризуемый kit нового репо (дерево зеркалит целевой репо: `.openclaw/agents/*.md`, `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, `README.md`, `CHANGELOG.md`, `docs/**`) |
|
||
| `onboarding/README.md` | создать | устройство kit: словарь плейсхолдеров, правило «канон не форкается» (что копируется live, что шаблонизируется) |
|
||
| `scripts/onboard_project.py` | создать | операторский turnkey-CLI: `plan` (dry-run, дефолт) / `apply` / `verify`; идемпотентность; отчёт |
|
||
| `docs/operations/ONBOARDING.md` | создать | runbook: последовательность, ручные шаги (env+рестарт, UI-only Plane), верификация, откат |
|
||
| `docs/operations/SETUP_WEBHOOKS.md` | обновить | обобщить per-repo Gitea-webhook секцию (сейчас примеры захардкожены на enduro-trails); сослаться на ONBOARDING.md |
|
||
| `tests/test_onboarding_kit.py` | создать | структура kit, канон промптов, reviewer-gate, INFRA/AGENTS/CONTRIBUTING |
|
||
| `tests/test_onboarding_script.py` | создать | рендер/плейсхолдеры, registry round-trip, dry-run/идемпотентность, план Plane/Gitea (моки) |
|
||
| `tests/test_onboarding_invariants.py` | создать | `src/**` не тронут логикой онбординга; снапшот `STAGE_TRANSITIONS`/`QG_CHECKS` |
|
||
| `CLAUDE.md`, `docs/architecture/README.md`, `CHANGELOG.md` | обновить | golden source: раздел «Онбординг проектов (ORCH-009)», запись changelog |
|
||
| `src/**` | **не менять** | NFR-1; скрипту разрешён **read-only import** `src.projects._parse_projects_json` / констант `src.plane_sync._PLANE_NAME_TO_KEY` для round-trip и точных имён (не дублировать литералы) — допустимость импорта vs снапшот-фикстура решает архитектор |
|
||
|
||
Справочные источники kit (read-only): `.openclaw/agents/*.md`, `docs/_templates/` (16 скелетов),
|
||
`docs/_standards/` (3 стандарта), `docs/operations/INFRA.md` (образец структуры RUNBOOK).
|
||
|
||
---
|
||
|
||
## 3. Функциональные требования
|
||
|
||
### FR-1 — Onboarding-kit: состав каркаса нового репо (BR-3/BR-5/BR-6)
|
||
`onboarding/repo-skeleton/` содержит (минимум):
|
||
|
||
```
|
||
.openclaw/agents/{analyst,architect,developer,reviewer,tester,deployer}.md ← шаблоны промптов
|
||
CLAUDE.md ← паспорт проекта (per-repo канон, Ф-8)
|
||
AGENTS.md ← точка входа агентов: карта доков + правила ведения
|
||
CONTRIBUTING.md ← канон процесса: где что лежит, как вести
|
||
README.md ← entrypoint: что это, quickstart, ссылки
|
||
CHANGELOG.md ← пустой каркас
|
||
docs/ARCHITECTURE.md ← код-карта/потоки/БД (заполняется по мере жизни)
|
||
docs/PIPELINE.md ← стадии, QG, агенты (ссылается на _standards)
|
||
docs/PRODUCT_VISION.md ← зачем проект (BRD-свод)
|
||
docs/operations/INFRA.md ← обязательный RUNBOOK (см. FR-3)
|
||
docs/architecture/adr/ ← реестр сквозных ADR (канон орка, §1.4 BRD)
|
||
docs/work-items/.gitkeep
|
||
docs/history/.gitkeep
|
||
docs/_templates/ ← live-копия канона орка в момент онбординга (BR-2)
|
||
docs/_standards/ ← live-копия канона орка в момент онбординга (BR-2)
|
||
.env.example ← заготовка карты env (без секретов)
|
||
```
|
||
|
||
- **Параметризация** — единый словарь плейсхолдеров (минимум): `{{PROJECT_NAME}}`, `{{REPO}}`,
|
||
`{{WORK_ITEM_PREFIX}}`, `{{PLANE_PROJECT_ID}}`, `{{STACK}}`, `{{TEST_CMD}}`,
|
||
`{{PROD_PORT}}`/`{{STAGING_PORT}}` (расширяемо; единый синтаксис, фиксирует архитектор).
|
||
- **Ссылочная целостность:** каждый путь, на который ссылаются kit-промпты/AGENTS.md, существует
|
||
в каркасе (проверяемо тестом).
|
||
- **Правило «канон не форкается» (BR-2):** `docs/_templates/` и `docs/_standards/` НЕ хранятся
|
||
второй редактируемой копией в kit — копируются скриптом из живого канона репо орка в момент
|
||
материализации. В kit хранятся только параметризуемые дельты (промпты, паспорт, AGENTS,
|
||
CONTRIBUTING, README, INFRA и пр.).
|
||
|
||
### FR-2 — Шаблоны промптов 6 ролей по канону 52d/92 (BR-3/BR-4)
|
||
Каждый из 6 шаблонов промптов:
|
||
- 5 обязательных XML-секций в нормативном порядке `<context>` → `<task>` → `<deliverables>` →
|
||
`<constraints>` → `<output_format>`; `<success_criteria>`; `<escalation>` у
|
||
developer/reviewer/tester (после `</success_criteria>`); `<thinking>` у решающих ролей —
|
||
как в эталоне `.openclaw/agents/` (ORCH-077/092).
|
||
- Запреты в формате «❌ X → ✅ Y».
|
||
- Директивы доки (жёстко): читай `CLAUDE.md`(паспорт)/`AGENTS.md`/`docs/ARCHITECTURE.md`/ADR
|
||
ПЕРЕД работой; пиши артефакты в `docs/work-items/<id>/` по `docs/_standards/PIPELINE_DOCS.md`
|
||
(скелеты из `docs/_templates/`); архитектор фиксирует решения в `06-adr/` + сквозные в
|
||
`docs/architecture/adr/adr-NNNN-slug.md`; каждый обновляет `CHANGELOG.md`/релевантную доку.
|
||
- **Reviewer:** содержит gate «документация обновлена? нет → `verdict: REQUEST_CHANGES`».
|
||
- Эмиссия 6-польной frontmatter-схемы 52c (`work_item`/`stage`/`author_agent`/`status`/
|
||
`created_at`/`model_used`) — аддитивно; machine-verdict ключи и значения байт-в-байт
|
||
(`verdict:`/`result:`/`staging_status:`/`deploy_status:`/`security_status:`); копируемые
|
||
примеры — с плейсхолдерами `<YYYY-MM-DD>`/`<resolve по конфигу>` (анти-паттерн ORCH-092 учтён).
|
||
- Стек-специфика (язык/тесты/команды) — только через плейсхолдеры; никаких унаследованных
|
||
орк-литералов (порты 8500/8501, «ORCH-», self-hosting-правила орка) в материализованном виде.
|
||
- Языковая политика: по канону орка (5 ru + deployer en, нормативно ADR-001 D2 ORCH-092);
|
||
отступление — только решением архитектора в ADR.
|
||
|
||
### FR-3 — INFRA.md шаблон: обязательные секции (BR-6)
|
||
Шаблон `docs/operations/INFRA.md` нового проекта содержит секции: топология (контейнеры, порты
|
||
прод/staging, сеть, тома, БД); карта env-переменных (дескрипторы в репо; секреты ТОЛЬКО в `.env`
|
||
на хосте; `.env.example` — канон; `docker-compose.yml`/`Dockerfile` трекаются в гите); границы
|
||
доступа; эксплуатационные предупреждения, включая **риски общего хоста** (соседние контейнеры,
|
||
общие ресурсы; факт: хост впритык — см. `docs/epics/self-evolution.md` С-3). Существующий
|
||
`docs/operations/INFRA.md` орка с self-hosting-предупреждениями (общая БД/очередь/групповой риск
|
||
рестарта) — не модифицируется этой задачей (read-only образец).
|
||
|
||
### FR-4 — Onboarding-скрипт: провижининг (BR-1/BR-7/BR-9/BR-11)
|
||
`scripts/onboard_project.py` (вход: имя проекта, repo, префикс work-item, параметры стека):
|
||
- **Gitea:** создать репо (API), создать per-repo webhook (`push`/`pull_request`/`status`,
|
||
HMAC-secret из/для `.env` — формат `SETUP_WEBHOOKS.md`); материализовать kit → **initial push
|
||
в свежесозданный пустой репо** (единственный разрешённый push; в существующие репо — никогда).
|
||
- **Plane:** создать проект (или принять существующий `--plane-project-id`); создать статусы со
|
||
**точными** именами из `_PLANE_NAME_TO_KEY` (22 имени; `STOP` — группа `cancelled`,
|
||
`Confirm Deploy` — отдельный статус; группы фиксирует архитектор по `plane_sync`) и лейблы
|
||
`autoApprove`/`autoDeploy`/`Bug`. Недоступное через API CE → пункт отчёта «ручной шаг» со
|
||
ссылкой на runbook (fail-safe, не падение).
|
||
- **Реестр:** сгенерировать запись `ORCH_PROJECTS_JSON` (полный новый массив или диф —
|
||
фиксирует архитектор), **валидную через фактический `projects._parse_projects_json`**;
|
||
вывести оператору инструкцию «добавь в `.env` + управляемый рестарт». Скрипт сам `.env` прода
|
||
не правит и контейнер не рестартит (NFR-2).
|
||
- **Режимы:** `plan` (дефолт; полный план без единой мутации), `apply` (исполнение),
|
||
`verify` (см. FR-5). Идемпотентность: повторный `apply` обнаруживает существующее
|
||
(репо/webhook/статусы/лейблы/файлы) и пропускает с пометкой; ничего не удаляет и не
|
||
перезаписывает существующий контент без явного флага.
|
||
- **Прозрачность:** лог каждого шага + итоговый отчёт: `created / skipped(exists) / manual-step`.
|
||
- **Webhook Plane:** не создаётся (workspace-level уже существует, Ф-6) — только проверка в verify.
|
||
|
||
### FR-5 — Верификация (BR-10)
|
||
- `verify`-режим скрипта: запись реестра парсится (`_parse_projects_json` round-trip → поля
|
||
совпадают); статусы проекта резолвятся (все логические ключи, включая `confirm_deploy`/`stop`);
|
||
лейблы присутствуют; Gitea-webhook существует и активен; kit-файлы в репо (включая 6 промптов,
|
||
AGENTS.md, INFRA.md, `_templates`/`_standards`); нет неразрешённых плейсхолдеров.
|
||
- **Smoke на песочнице** (runbook, операторский): онбордить sandbox-проект → создать тестовую
|
||
задачу → стадия analysis в песочнице → убедиться: агент прочитал доку проекта (следы в
|
||
выводе/артефактах) и записал артефакты в `docs/work-items/<id>/` по канону. Контур песочницы
|
||
(staging 8501 / одноразовый sandbox) фиксирует архитектор в ADR + runbook.
|
||
|
||
### FR-6 — Runbook ONBOARDING.md (BR-1/BR-8)
|
||
Полный чеклист онбординга: предусловия (токены, доступы) → шаги скрипта → **операторские шаги**
|
||
(env+рестарт — с предупреждением self-hosting: рестарт прода = групповое окно, выполнять
|
||
осознанно; UI-only шаги Plane, напр. drag-and-drop порядок статусов) → верификация (verify +
|
||
smoke) → откат (удаление созданного — вручную, скрипт не удаляет). Каждый ручной шаг — с командой
|
||
проверки результата.
|
||
|
||
---
|
||
|
||
## 4. Изменения API
|
||
**Нет.** Новые/изменённые HTTP-эндпоинты оркестратора не вводятся; вебхук-контракты не меняются.
|
||
(Onboarding-CLI — операторский инструмент вне FastAPI-приложения.)
|
||
|
||
## 5. Изменения схемы БД
|
||
**Нет.** Общая БД не читается и не пишется скриптом (NFR-2).
|
||
|
||
## 6. Требования к новым/изменённым QG checks
|
||
**Нет.** Реестр `QG_CHECKS`/`check_*`/`STAGE_TRANSITIONS` — байт-в-байт (контроль — снапшот-тест,
|
||
TC-18). Онбординг — операторская способность, не гейт конвейера.
|
||
|
||
---
|
||
|
||
## 7. Совместимость / регресс
|
||
- **Нулевая регрессия кода:** `src/**` не меняется → поведение конвейера для enduro/orchestrator
|
||
идентично; полный регресс `tests/` остаётся зелёным.
|
||
- **Kill-switch не требуется:** способность активируется только явным запуском операторского CLI;
|
||
в горячих путях конвейера нового кода нет.
|
||
- **Обратимость:** удаление `onboarding/`/`scripts/onboard_project.py`/runbook возвращает репо в
|
||
исходное состояние; созданные онбордингом внешние сущности сносятся вручную по разделу
|
||
«Откат» runbook.
|
||
- **Совместимость канонов:** kit-промпты проходят те же структурные требования, что эталонные
|
||
(анти-дрейф NFR-4); обновление канона орка автоматически подхватывается live-copy частью kit
|
||
(BR-2), шаблонные дельты — через обычные PR с reviewer-gate.
|
||
|
||
---
|
||
|
||
## 8. Артефакты pipeline (создать/обновить в ТОМ ЖЕ PR)
|
||
- `docs/work-items/ORCH-009/06-adr/ADR-001-…` — решения архитектора (раскладка kit, синтаксис
|
||
плейсхолдеров, copy-vs-template split по файлам, импорт `src` из скрипта vs снапшот, контур
|
||
песочницы, языковая политика kit-deployer).
|
||
- `docs/architecture/README.md` — раздел «Онбординг проектов (ORCH-009)».
|
||
- `CLAUDE.md` — краткий абзац о способности онбординга.
|
||
- `CHANGELOG.md` — запись `feat:`.
|
||
- `docs/operations/ONBOARDING.md` (новый), `docs/operations/SETUP_WEBHOOKS.md` (обобщение).
|
||
- `07-infra-requirements.md` — предусловия онбординга (токены/доступы), заполняет архитектор.
|
||
|
||
---
|
||
|
||
## 9. Инварианты (не нарушать)
|
||
- `src/**` без изменений; `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict ключи/схема
|
||
БД — байт-в-байт (NFR-1).
|
||
- Скрипт: не рестартит/не останавливает прод-контейнер; не пушит в `main` существующих репо
|
||
(INV-4 — мерж только через PR-merge API — не затрагивается: initial push идёт в свежесозданный
|
||
пустой репо, не являющийся участником конвейера до регистрации); не удаляет внешние сущности;
|
||
секреты в гит не попадают (NFR-2/NFR-3).
|
||
- Никаких сетевых вызовов в тестах (NFR-5); никаких новых обязательных pip-зависимостей без
|
||
обоснования в ADR.
|
||
- Эталонные промпты орка `.openclaw/agents/*.md` этой задачей не модифицируются (они — read-only
|
||
образец; их правка = отдельные задачи канона).
|
||
|
||
---
|
||
|
||
## 10. Открытые вопросы для архитектора (не блокируют анализ)
|
||
- OQ-1: Раскладка kit — `onboarding/repo-skeleton/` (предложение) vs `docs/_onboarding/` vs
|
||
`scripts/onboarding/`; где словарь плейсхолдеров.
|
||
- OQ-2: Механизм подстановки — stdlib (`str.replace`/`string.Template`) без новых зависимостей
|
||
(рекомендация) vs шаблонизатор (новая зависимость — потребует обоснования).
|
||
- OQ-3: Copy-vs-template split: какие файлы kit — live-copy канона, какие — параметризуемые
|
||
шаблоны (минимум по BR-2: `_templates`/`_standards` — live-copy).
|
||
- OQ-4: Скрипту импортировать `src.projects`/`src.plane_sync` (точные имена/парсер, нет
|
||
дублирования) vs автономный снапшот констант с тестом синхронизации.
|
||
- OQ-5: Plane API CE: фактическая доступность создания проекта/статусов/лейблов — что уходит в
|
||
ручные шаги runbook.
|
||
- OQ-6: Контур песочницы для smoke (staging 8501 vs одноразовый sandbox-проект) и судьба
|
||
sandbox-артефактов после прогона.
|
||
- OQ-7: Языковая политика kit-промптов для не-self-hosting проектов (рекомендация: канон орка,
|
||
deployer — en).
|
||
- OQ-8: Защита `main` нового репо в Gitea (branch protection): не должна ломать PR-merge API
|
||
конвейера — включать ли вообще (рекомендация: не включать, зафиксировать в runbook).
|