orchestrator/docs/work-items/ORCH-009/12-review.md

verdict, work_item, stage, author_agent, status, created_at, model_used, type, work_item_id, version

verdict	work_item	stage	author_agent	status	created_at	model_used	type	work_item_id	version
APPROVED	ORCH-009	review	reviewer	approved	2026-06-10	claude-fable-5	review	ORCH-009	2

Review ORCH-009 — Turnkey-онбординг проектов (kit + CLI + runbook) — re-review (цикл 2)

Ветка: feature/ORCH-009-turnkey-plane · Diff vs origin/main: 46 файлов, +5478/−12. Состав: kit onboarding/repo-skeleton/ (28 файлов), CLI scripts/onboard_project.py (1090 строк), runbook docs/operations/ONBOARDING.md, 3 онбординг-тест-модуля (83 теста), golden-source доки, ADR×2 + индекс.

Контекст цикла: review v1 (APPROVED, 3×P2/2×P3) → testing PASS → re-test merge-gate упал на средовых не-герметичных тестах ORCH-41-эры (прод-env ORCH_AGENT_FALLBACK_MODEL/ ORCH_AGENT_MODEL_DEFAULT) → откат на development → фикс e903818 (герметизация tests/test_resolve_agent_{model,effort}.py) + регенерация 17-security-report.md (b26a391). Этот review: независимая проверка дельты цикла + выборочная верификация клеймов v1.

Summary

APPROVED. P0/P1 нет. Дельта цикла (фикс герметичности тестов) корректна, трассирована к ORCH-074 ADR-001 Решение 3 и сохраняет его инвариант; полный регресс теперь зелёный под фактическим прод-env (перепроверено мной: 1713 passed, exit 0 — ровно та среда, что валила merge-gate до фикса). Клеймы review v1 выборочно перепроверены и подтверждены. Переносятся 3×P2 (харднинг краевых путей CLI, не фикшены — легитимно, follow-up) + 3×P3. Документация обновлена в том же PR по всем точкам, включая отдельную CHANGELOG-запись про сам фикс тестов.

Оси проверки

Ось 1 — Соответствие ТЗ (02-trz.md, 03-acceptance-criteria.md) — ✅

Требование	Статус	Чем подтверждено
FR-1 состав kit (19 элементов, анти-форк канона)	✅	TC-01/02 зелёные; `docs/_templates
FR-2 канон 52d/92 промптов (5 секций, ❌→✅, <escalation>, 52c-схема, verdict-ключи байт-в-байт, плейсхолдерные даты/модели)	✅	TC-03…06 зелёные; verdict-ключи в kit-промптах сверены grep'ом (verdict:/staging_status:/deploy_status:/security_status: на месте)
FR-2 reviewer-gate доки (AC-3)	✅	kit reviewer.md:65: «документация НЕ обновлена → вердикт ОБЯЗАТЕЛЬНО REQUEST_CHANGES» — прочитано лично
FR-3 INFRA.md шаблон	✅	TC-19 зелёный (топология/env/границы/риски общего хоста); INFRA орка не тронут (diff пуст)
FR-4 CLI plan/apply/verify	✅	Код прочитан полностью: plan GET-only (рендер in-memory), apply идемпотентный ensure без delete, 22 статуса из _PLANE_NAME_TO_KEY + STATE_GROUPS 1:1 c ADR D5, CE-отказ → ManualStep → manual-step (fail-safe); TC-13…18 зелёные
FR-5 verify	✅	round-trip фактическим парсером, резолв всех 22 имён, лейблы, webhook active, полнота kit (VERIFY_KIT_FILES), скан {{…}}, канон ≥16/≥3
FR-6 runbook	✅	ONBOARDING.md прочитан: слои 0→6 в порядке BR-1, каждый 🖐-шаг с командой проверки, self-hosting-предупреждение «групповое окно» (§4.2), workspace-webhook — «существует, только проверка» (§1.5), откат §6
§4/§5 нет API/БД изменений	✅	diff src/** пуст (проверено лично)
§9 инварианты	✅	git diff origin/main...HEAD -- src/ .openclaw/ docs/_templates/ docs/_standards/ docs/operations/INFRA.md requirements.txt — пусто; сетевых вызовов в тестах нет (фейк-клиенты); новых pip-зависимостей нет
AC-12 полный регресс	✅	1713 passed, 0 failed, exit 0 — мой прогон в worktree ветки под фактическим хост-env (до фикса здесь было 2 failed)
AC-13 операторский smoke	⏳	По построению операторский (ADR D8); «Журнал smoke-прогонов» — плейсхолдер. Обязателен ДО Confirm Deploy — см. handoff

Ось 2 — Соответствие ADR (06-adr/ADR-001 D1–D11, сквозной adr-0035) — ✅

• D1 top-level onboarding/ ✅; D2 {{NAME}} + str.replace + обязательный пост-скан (PLACEHOLDER_RE, ValueError в materialize_kit) + биекция словаря тестом ✅; D3 live-copy verbatim, существующие файлы не перезаписываются ✅; D4 закрытый список импортов src — в скрипте ровно три (settings, _PLANE_NAME_TO_KEY, _parse_projects_json), загвожден AST-тестом TC-21 ✅; D5 STATE_GROUPS 1:1 с таблицей ADR (22 имени, set-равенство с _PLANE_NAME_TO_KEY тестом; STOP→cancelled; терминальные группы только Done/Cancelled/STOP; Rejected→started) ✅; D6 auto_init=False, переиспользование глобального HMAC-секрета, push только в свежесозданный/пустой репо ✅; D7 merged-full-array
  • round-trip + .env read-only ✅; D8 smoke на staging 8501, журнал в runbook ✅; D9 5 ru + deployer en с «Do NOT translate»-гардом и рамкой shared-host-гардрейлов (прочитано лично) ✅; D10 runbook §2.3 «branch protection НЕ включать» ✅; D11 plan/apply/verify, чистый build_plan, инжектируемые клиенты, отчёт created/skipped(exists)/manual-step/planned/ error, exit-коды 0/2/1 ✅.
• Трассировка (docs/_standards/TRACEABILITY.md) — дельта цикла:
  • tests/test_resolve_agent_{model,effort}.py несут маркеры ORCH-41/ORCH-074 — сверено с docs/work-items/ORCH-074/06-adr/ADR-001-model-name-validation.md Решение 3 (G4): инвариант = «shipped-дефолт agent_fallback_model остаётся ""». Фикс переводит ассерт с env-backed singleton на класс-дефолт поля (model_fields[...].default == "") — это и есть подлинный инвариант ADR (заводской дефолт, а не рантайм-конфиг оператора); never-break ассерты is_valid_model — байт-в-байт. Инвариант сохранён и уточнён, обоснование — в коммит-месседже и инлайн-комментариях со ссылкой на ADR. Чужой инвариант не сломан → finding нет.
  • docs/architecture/adr/README.md — бэкфилл строк 0032–0035 сверен: все 4 файла (adr-0032-bug-fast-track, adr-0033-sidecar-watchdog, adr-0034-lessons-journal, adr-0035-turnkey-project-onboarding) существуют, привязки задач корректны, «текущий максимум 0035» верен.
  • docs/operations/SETUP_WEBHOOKS.md — обобщение per-repo усиливает инвариант одного глобального HMAC-секрета (явное предупреждение про ротацию на всех репо разом).
• Инварианты NFR-1/INV-4: снапшот-тесты STAGE_TRANSITIONS/QG_CHECKS зелёные; push — только initial в пустой репо вне конвейера; PR-merge API не затрагивается.

Ось 3 — Качество кода — ✅ (с переносными P2 ниже)

• CLI: чистое разделение слоёв (ядро без I/O / тонкие клиенты / режимы), docstrings на всех публичных функциях, единственная точка subprocess (только git, токен в логе маскируется ://***@), ManualStep fail-safe вместо падений, delete-операций нет вовсе, секрет в отчёте *** + тест non-leak. Тесты содержательные: AST-проверка закрытого списка импортов, monkeypatch-мины на мутации в dry-run, негативные CE-сценарии, set-равенство против дрейфа констант — не тривиальные.
• Фикс герметичности (дельта цикла) — корректен: autouse-фикстуры пиняют shipped-дефолты (зеркально между файлами-сиблингами), в чистом env поведение байт-эквивалентно; класс среды merge-gate re-test (прод-env) теперь покрыт. Перепроверено прогоном: 1713 passed под хост-env. Правка существующих тестов вне инвентаря ТЗ §2 — легитимна: инвентарь «рабочее предложение», ни один инвариант §9 не запрещает правку тестов; без неё PR непроходим через merge-gate (латентная мина main, детонированная сменой прод-env).
• Багфикс-трек (ORCH-019, BR-4): не применим — задача не Bug, маршрут полный.

Ось 4 — Документация — ✅ ОБНОВЛЕНА В ТОМ ЖЕ PR

Точка	Статус
CLAUDE.md — раздел «Turnkey-онбординг проектов (ORCH-009)»	✅
docs/architecture/README.md — раздел + ссылки на оба ADR	✅ (diff прочитан, фактам соответствует)
CHANGELOG.md — детальная feat-запись + отдельная под-запись про фикс герметичности тестов	✅ (дельта цикла задокументирована — образцово)
ADR per-WI 06-adr/ADR-001 + сквозной adr-0035 + индекс adr/README.md	✅
docs/operations/ONBOARDING.md (новый runbook)	✅
docs/operations/SETUP_WEBHOOKS.md — обобщён per-repo	✅
onboarding/README.md — устройство kit, словарь, анти-форк	✅
README «Известные ограничения» (ORCH-079)	N/A — проверено лично: открыты 3 пункта (Telegram 48h / intra-repo deps ORCH-026 / пакетный автоном Этап 1) — ни один этим PR не закрывается
17-security-report.md	✅ security_status: PASS (0 secrets, 0 blocking)
08-data-requirements.md отсутствует	Легитимно: гейт check_analysis_complete требует 01–04; ТЗ §5 «изменений БД нет»

Findings

P0 — Blocker

• (нет)

P1 — Must fix

• (нет)

P2 — Should fix (перенос из review v1 — не фикшены, перепроверены: всё ещё в коде; follow-up, не блокируют)

• Quoted-значение в .env → тихая потеря существующих записей в merged-выводе. read_existing_registry (строка ~355) возвращает значение после = как есть; кавычки → json.loads в merged_projects_json молча даёт existing=[] → merged-массив только с новым проектом, а runbook §4.1 велит «заменить строку». Доминирующий путь безопасен (pydantic снимает кавычки), потому P2. Рекомендация: strip("'\"") в фоллбеке + GAP-warning, если строка в .env есть, а existing пуст. (ADR D7 «существующие не теряются».)
• GiteaClient.create_repo: фоллбек POST /user/repos может создать репо в чужом namespace (строки ~474–477): owner не org и не юзер токена → репо рождается под юзером токена, последующие шаги по owner/repo дают 404/manual-step. Рекомендация: сверять owner.login ответа с запрошенным; расхождение → manual-step.
• CE-деградация Plane + успешный Gitea в одном apply запекает литерал <assigned-on-apply> в запушенный паспорт (build_params → PLANE_PROJECT_ID); скан ловит только {{…}}. Рекомендация: при неразрешённом PLANE_PROJECT_ID деградировать kit.materialize/kit.push в manual-step ИЛИ добавить <assigned-on-apply> в скан verify.

P3 — Nice to have

• --env-file игнорируется в plan (run_plan → _registry_instructions(report, params, None); main() его в run_plan и не передаёт): превью merged-массива может расходиться с apply.
• Push-URL с oauth2:<token>@ остаётся в .git/config temp-каталога после успешного apply (cleanup нет). Рекомендация: чистить на успехе, на ошибке сохранять для дебага.
• (новое) run_apply: шаг registry.emit добавляется со статусом CREATED до _registry_instructions, который на ошибке round-trip добавляет второй шаг registry.emit со статусом ERROR → дубль step-id в отчёте (exit-код при этом честный — 1). Косметика отчёта.

Документация

Обновлена полностью в том же PR (таблица оси 4). Несоответствий «код изменён — дока молчит» нет; дельта цикла (фикс тестов) получила собственную CHANGELOG-запись с диагнозом и обоснованием; обзорная витрина README задачей не затрагивается (проверено: открытые ограничения не про онбординг).

Для следующей стадии (testing) — handoff

1. AC-13 (операторский smoke, ADR D8) — единственный непокрытый pytest'ом AC: прогон по runbook §5.2 (staging 8501, sandbox SMK) должен быть выполнен и запротоколирован в «Журнале smoke-прогонов» ONBOARDING.md, ссылка — из 13-test-report.md. Обязателен до Confirm Deploy (человеческий гейт — точка контроля сохраняется).
2. Средовая мина merge-gate обезврежена фиксом e903818: полный регресс зелёный и в чистом env, и под прод-env (1713 passed, проверено в этом review) — спец-обвязка прогона больше не нужна.
3. 13-test-report.md в дереве — от прошлого цикла (до e903818): его строка «PR эти файлы не трогает» про tests/test_resolve_agent_* устарела. Перегенерировать отчёт штатно (артефакт чужой стадии — в этом review не правился).