Files

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

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

21 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

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).

21 KiB Raw Blame History Unescape Escape