147 lines
13 KiB
Markdown
147 lines
13 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
|
||
---
|
||
|
||
# 03 — Критерии приёмки (Acceptance Criteria): ORCH-009 — Turnkey-онбординг проектов
|
||
|
||
Work Item: **ORCH-009** · Repo: **orchestrator** · Стадия: analysis
|
||
|
||
Формат: каждый критерий — чёткое условие **PASS/FAIL**, проверяемое буквально по файлам
|
||
репозитория и детерминированным тестам (без сети). AC-13 — единственный операторский
|
||
(документированный smoke), его автоматизируемая часть вынесена в AC-2/AC-12.
|
||
|
||
---
|
||
|
||
## AC-1 — Kit полон (состав каркаса)
|
||
**Условие:** инспекция `onboarding/repo-skeleton/` (или каталога, выбранного архитектором в ADR).
|
||
- **PASS:** присутствуют все элементы FR-1: 6 шаблонов промптов (`analyst/architect/developer/
|
||
reviewer/tester/deployer`), `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, `README.md`,
|
||
`CHANGELOG.md`, `docs/ARCHITECTURE.md`, `docs/PIPELINE.md`, `docs/PRODUCT_VISION.md`,
|
||
`docs/operations/INFRA.md`, `docs/architecture/adr/`, `docs/work-items/`, `docs/history/`,
|
||
`.env.example`; материализация добавляет live-копии `docs/_templates/` + `docs/_standards/`.
|
||
- **FAIL:** отсутствует любой элемент состава, либо промптов меньше 6.
|
||
|
||
## AC-2 — Промпты kit соответствуют канону 52d/92
|
||
**Условие:** структурные тесты по каждому из 6 шаблонов промптов.
|
||
- **PASS:** в каждом — 5 обязательных XML-секций в нормативном порядке `<context>→<task>→
|
||
<deliverables>→<constraints>→<output_format>`; запреты в формате «❌ → ✅»; `<escalation>` у
|
||
developer/reviewer/tester; директивы «читай паспорт/AGENTS.md/доку ПЕРЕД работой» и «пиши
|
||
артефакты в `docs/work-items/<id>/`»; эмиссия 6-польной frontmatter-схемы 52c с
|
||
плейсхолдерными примерами дат/моделей; machine-verdict ключи у ролей-вердиктов байт-в-байт
|
||
(`verdict:` / `result:` / `staging_status:` / `deploy_status:` / `security_status:`).
|
||
- **FAIL:** нарушен порядок/состав секций, отсутствует любой verdict-ключ или директива доки,
|
||
пример frontmatter содержит захардкоженные дату/модель.
|
||
|
||
## AC-3 — Reviewer-gate на обновление доки
|
||
**Условие:** шаблон `reviewer.md` в kit.
|
||
- **PASS:** содержит явное правило: документация (CHANGELOG/релевантные доки/ADR) обновлена в том
|
||
же PR; нет → `verdict: REQUEST_CHANGES`.
|
||
- **FAIL:** правило отсутствует или сформулировано как необязательное.
|
||
|
||
## AC-4 — Языковая политика kit
|
||
**Условие:** проверка языка шаблонов промптов против решения ADR (дефолт — канон орка).
|
||
- **PASS:** языковая раскладка соответствует зафиксированной в ADR (по умолчанию: 5 ru +
|
||
deployer en, как ADR-001 D2 ORCH-092); отступление — только с обоснованием в ADR.
|
||
- **FAIL:** язык промптов противоречит ADR, либо политика нигде не зафиксирована.
|
||
|
||
## AC-5 — Материализация: плейсхолдеры и отсутствие утечек
|
||
**Условие:** рендер kit с тестовыми параметрами (`PROJECT_NAME`, `REPO`, `WORK_ITEM_PREFIX` и т.д.).
|
||
- **PASS:** все плейсхолдеры подставлены; в результате нет ни одного неразрешённого плейсхолдера
|
||
(grep по синтаксису из ADR); нет утечек орк-специфики, где должен быть параметр (литералы
|
||
`ORCH-` как префикс work-item чужого проекта, порты 8500/8501, self-hosting-правила орка);
|
||
пути, на которые ссылаются отрендеренные промпты/AGENTS.md, существуют в каркасе.
|
||
- **FAIL:** найден неразрешённый плейсхолдер, орк-литерал вместо параметра или битая ссылка
|
||
на несуществующий путь.
|
||
|
||
## AC-6 — Registry round-trip через фактический парсер
|
||
**Условие:** скрипт генерирует запись реестра для тестового проекта.
|
||
- **PASS:** сгенерированный JSON парсится `projects._parse_projects_json` без ошибок; полученный
|
||
`ProjectConfig` несёт исходные `plane_project_id`/`repo`/`work_item_prefix`/`name`; существующие
|
||
записи реестра не модифицируются и не теряются.
|
||
- **FAIL:** парсер отвергает запись, поля искажены, либо генерация ломает/теряет существующие записи.
|
||
|
||
## AC-7 — План Plane: точные статусы и лейблы
|
||
**Условие:** `plan`-режим для нового проекта (моки сети).
|
||
- **PASS:** план провижининга содержит ВСЕ канонические имена статусов из `_PLANE_NAME_TO_KEY`
|
||
(включая `Confirm Deploy` и `STOP` с группой `cancelled`) и лейблы `autoApprove`/`autoDeploy`/
|
||
`Bug`; имена байт-в-байт совпадают с константами `src/plane_sync.py` (или их синхронизированным
|
||
снапшотом по OQ-4); недоступные через API шаги помечены `manual-step` со ссылкой на runbook.
|
||
- **FAIL:** пропущен/искажён любой статус или лейбл; недоступный шаг молча отброшен.
|
||
|
||
## AC-8 — План Gitea: репо + per-repo webhook; dry-run без мутаций
|
||
**Условие:** `plan`-режим (моки сети).
|
||
- **PASS:** план содержит создание репо, создание webhook с events `push`/`pull_request`/`status`
|
||
и HMAC-secret (секрет — для `.env` оператора, не в гит), материализацию kit + initial push в
|
||
свежесозданный репо; в режиме `plan` не выполняется НИ ОДНОЙ мутации (ни одного
|
||
POST/PUT/DELETE-вызова в моках, ни одной записи на диск вне отчёта).
|
||
- **FAIL:** план неполон, или dry-run произвёл мутацию.
|
||
|
||
## AC-9 — Идемпотентность и безопасность apply
|
||
**Условие:** повторный `apply` на частично/полностью созданном проекте (моки: сущности существуют).
|
||
- **PASS:** существующие сущности (репо/webhook/статусы/лейблы/файлы) распознаны и пропущены с
|
||
пометкой `skipped(exists)`; ничего не удалено и не перезаписано без явного флага; скрипт не
|
||
выполняет рестарт/останов контейнеров, не правит `.env` прода, не пушит в существующие репо
|
||
(в коде отсутствуют такие операции — проверяемо тестом/ревью); итоговый отчёт перечисляет
|
||
created/skipped/manual-step.
|
||
- **FAIL:** дублирование сущностей, любое удаление/перезапись без флага, любая операция
|
||
рестарта/push в существующий репо, отсутствие отчёта.
|
||
|
||
## AC-10 — INFRA.md шаблон: обязательные секции
|
||
**Условие:** инспекция шаблона `docs/operations/INFRA.md` в kit.
|
||
- **PASS:** присутствуют секции: топология (контейнеры/порты прод+staging/сеть/тома/БД);
|
||
карта env-переменных + правило секретов (только `.env` на хосте, `.env.example` — канон);
|
||
границы доступа; предупреждения о рисках общего хоста. Существующий `docs/operations/INFRA.md`
|
||
орка (self-hosting-предупреждения) этой задачей не изменён.
|
||
- **FAIL:** отсутствует любая обязательная секция, либо изменён INFRA.md самого орка.
|
||
|
||
## AC-11 — Runbook ONBOARDING.md полон
|
||
**Условие:** инспекция `docs/operations/ONBOARDING.md`.
|
||
- **PASS:** покрывает все слои BR-1 в последовательности: предусловия (токены/доступы) → Plane
|
||
(проект/статусы/лейблы) → Gitea (репо/webhook) → kit (материализация/push) → регистрация
|
||
(env-строка + операторский управляемый рестарт с self-hosting-предупреждением) → верификация
|
||
(`verify` + smoke на песочнице) → откат; каждый ручной шаг помечен и снабжён командой проверки;
|
||
Plane workspace-webhook описан как существующий (проверка, не создание).
|
||
- **FAIL:** пропущен слой, ручной шаг не помечен/без проверки, или runbook требует
|
||
автоматического рестарта прода.
|
||
|
||
## AC-12 — Инварианты: src/** не тронут
|
||
**Условие:** diff PR + снапшот-тест.
|
||
- **PASS:** `git diff` PR не содержит изменений `src/**`; снапшот `STAGE_TRANSITIONS` и реестра
|
||
`QG_CHECKS` совпадает с эталоном; эталонные промпты `.openclaw/agents/*.md` орка не изменены;
|
||
полный регресс `tests/` зелёный.
|
||
- **FAIL:** любой diff в `src/**` или `.openclaw/agents/`, расхождение снапшота, красный регресс.
|
||
|
||
## AC-13 — Smoke: агент находит, использует и актуализирует доку (операторский)
|
||
**Условие:** документированный прогон по runbook на песочнице (контур — по ADR): онбординг
|
||
sandbox-проекта → тестовая задача → стадия analysis.
|
||
- **PASS:** агент песочницы по своему промпту прочитал доку проекта (следы чтения паспорта/
|
||
AGENTS.md в выводе или артефактах) и записал артефакты в `docs/work-items/<id>/` по канону
|
||
(структура соответствует `PIPELINE_DOCS.md`); результат прогона зафиксирован в runbook/отчёте
|
||
задачи. Для приёмки данной задачи прогон выполняется один раз и протоколируется.
|
||
- **FAIL:** агент не нашёл доку (артефакты вне канона/не созданы), либо прогон не запротоколирован.
|
||
|
||
---
|
||
|
||
## Сводная матрица AC ↔ BR/FR
|
||
|
||
| AC | BR | FR | Тип проверки |
|
||
|----|----|----|--------------|
|
||
| AC-1 | BR-5 | FR-1 | unit (структура kit) |
|
||
| AC-2 | BR-3 | FR-2 | unit (структурный канон) |
|
||
| AC-3 | BR-4 | FR-2 | unit |
|
||
| AC-4 | BR-3 | FR-2 | unit + ADR |
|
||
| AC-5 | BR-2/BR-5 | FR-1/FR-2 | unit (рендер) |
|
||
| AC-6 | BR-8 | FR-4 | integration (реальный парсер) |
|
||
| AC-7 | BR-7 | FR-4 | unit (план, моки) |
|
||
| AC-8 | BR-1/BR-9 | FR-4 | unit (план, моки) |
|
||
| AC-9 | BR-9/BR-11 | FR-4 | unit/integration (моки) |
|
||
| AC-10 | BR-6 | FR-3 | unit (структура) |
|
||
| AC-11 | BR-1/BR-8 | FR-6 | unit (структура дока) |
|
||
| AC-12 | NFR-1 | — | unit (снапшот) + ревью diff |
|
||
| AC-13 | BR-10 | FR-5 | ручной smoke (протоколируемый) |
|