From bd5d681083ae8f9460f5fafb21ab0978a7c05c50 Mon Sep 17 00:00:00 2001 From: claude-bot Date: Tue, 9 Jun 2026 14:32:28 +0300 Subject: [PATCH] analyst(ET): auto-commit from analyst run_id=459 --- docs/work-items/ORCH-077/01-brd.md | 150 ++++++++++++ docs/work-items/ORCH-077/02-trz.md | 227 ++++++++++++++++++ .../ORCH-077/03-acceptance-criteria.md | 133 ++++++++++ docs/work-items/ORCH-077/04-test-plan.yaml | 77 ++++++ 4 files changed, 587 insertions(+) create mode 100644 docs/work-items/ORCH-077/01-brd.md create mode 100644 docs/work-items/ORCH-077/02-trz.md create mode 100644 docs/work-items/ORCH-077/03-acceptance-criteria.md create mode 100644 docs/work-items/ORCH-077/04-test-plan.yaml diff --git a/docs/work-items/ORCH-077/01-brd.md b/docs/work-items/ORCH-077/01-brd.md new file mode 100644 index 0000000..8137863 --- /dev/null +++ b/docs/work-items/ORCH-077/01-brd.md @@ -0,0 +1,150 @@ +# 01 — BRD (бизнес-требования): ORCH-077 — ORCH-52d: оптимизация 6 системных промптов по Anthropic + +Work Item: **ORCH-077** · Repo: **orchestrator** (self-hosting) · Стадия: analysis + +## 1. Бизнес-контекст и проблема + +Эпик **ORCH-52** строит сквозной контракт документации конвейера тремя слоями: + +- **52b (ORCH-075)** — описательный стандарт документов: `docs/_standards/PIPELINE_DOCS.md` + (карта «стадия → агент → документ → гейт → machine-key») + копируемые скелеты в + `docs/_templates/`. +- **52c (ORCH-076)** — машинный контракт: единый `src/frontmatter.py` (reader + writer + + валидатор `validate_schema`/`REQUIRED_FIELDS`) и спека `docs/_standards/HANDOFF_PROTOCOL.md` + с **обязательной frontmatter-схемой** (`work_item`, `stage`, `author_agent`, `status`, + `created_at`, `model_used`). +- **52d (эта задача, ORCH-077)** — слой промптов: замыкающее звено. + +**Боль 1 (разрыв цепочки 52b→52c→52d).** 52c заложила writer и валидатор обязательной схемы, +но работает в режиме **обратной совместимости** (`frontmatter_validation_strict=False`, +warning-only) — агенты **физически не проставляют** эти поля в своих выходных документах. Пока +6 системных промптов не научены эмитить схему, петля 52 не замкнута: writer есть, валидатор +есть, а данных на входе нет. + +**Боль 2 (форма промптов).** 6 системных промптов агентов (`.openclaw/agents/*.md`) написаны +в свободной разнородной форме (часть по-русски, deployer — по-английски), без единой структуры. +Это снижает предсказуемость поведения агентов прода и затрудняет сопровождение. Канон Anthropic +по построению системных промптов (XML-разметка секций, few-shot с эталонами, явное место для +рассуждения, позитивные примеры рядом с запретами, литеральный scope) даёт измеримо более +стабильный выход. + +**Установленные факты (проверено в репозитории):** + +- Промпты в `.openclaw/agents/`: `analyst.md`, `architect.md`, `developer.md`, `reviewer.md`, + `tester.md`, `deployer.md` — все 6 в объёме. +- Модель/эффорт каждого агента резолвятся ТОЛЬКО из config (`resolve_agent_model` / + `resolve_agent_effort`, ORCH-41); frontmatter `model:` удалён как мёртвый (ORCH-074, тест + `tests/test_agent_frontmatter_no_model.py`). Все 6 ролей сейчас на `claude-opus-4-8`. +- Обязательная схема: `src/frontmatter.py::REQUIRED_FIELDS = + ("work_item", "stage", "author_agent", "status", "created_at", "model_used")`. +- Machine-verdict ключи (регистрозависимы, читаются гейтами ТОЛЬКО из frontmatter): + `verdict:` (12-review.md), `result:`/`verdict:`/`status:` (13-test-report.md), + `staging_status:` (15-staging-log.md), `deploy_status:` (14-deploy-log.md), + `security_status:` (17-security-report.md). + +## 2. Объём (scope) + +### В объёме + +- Переписать **все 6** промптов `.openclaw/agents/*.md` в едином каноне Anthropic с + XML-структурой секций: `` / `` / `` / `` / + `` (допустимы дополнительные семантические секции, напр. ``-подсказка). +- Добавить в каждый промпт **явную инструкцию эмитить обязательную frontmatter-схему 52c** + (`work_item` / `stage` / `author_agent` / `status` / `created_at` / `model_used`) в тех + выходных документах, которые роль авторствует, с конкретными для роли значениями + (`author_agent` = роль, `stage` = стадия роли, `model_used` = резолв ORCH-41). +- Few-shot: ссылки на скелеты 52b (`docs/_templates/`) и эталонные work item (ORCH-073 / ORCH-088) + как примеры заполнения; позитивные примеры рядом с запретами («делай Y вместо X»). +- Явное место для рассуждения (CoT/thinking) там, где это уместно для роли. +- Чёткие success-criteria артефакта стадии (что считается готовым выходом). +- Обновить документацию: `CLAUDE.md`, `docs/architecture/README.md`, ADR (per-work-item + + при необходимости сквозной), `CHANGELOG.md`. + +### Вне объёма + +- **Любая правка кода**: `src/config.py`, `src/agents/launcher.py`, `resolve_agent_model` / + `resolve_agent_effort`, `src/frontmatter.py` (сделана в 52c), `src/stages.py`, + `src/qg/checks.py`, `src/stage_engine.py`. +- **Включение жёсткой валидации** схемы (`frontmatter_validation_strict`) — остаётся `False` + (warning-only). 52d учит промпты эмитить схему добровольно; enforcement не включается. +- Изменение состава/семантики Quality Gates, `STAGE_TRANSITIONS`, набора machine-verdict ключей. +- Model-routing / смена моделей ролей (вне эпика). +- Изменение `tools:`-блока (разрешённые инструменты) в frontmatter промптов. + +## 3. Заинтересованные стороны + +- **Заказчик / Owner (Слава)** — принимает результат; ручной BRD-гейт. +- **Потребитель прямой** — 6 агентов прода, которые исполняют эти промпты на КАЖДОЙ задаче ВСЕХ + проектов (orchestrator + enduro-trails) из общего инстанса. +- **Косвенно затронуты** — все будущие work item (качество артефактов конвейера) и петля 52 + (наполнение frontmatter-схемы реальными данными). + +## 4. Бизнес-требования (BR) + +- **BR-1** — Все 6 промптов (`.openclaw/agents/*.md`) переписаны единым XML-стилем секций + (`` / `` / `` / `` / ``). +- **BR-2** — Каждый промпт **явно инструктирует** агента проставлять обязательную + frontmatter-схему 52c (все 6 полей) в выходных документах, которые роль авторствует, с + конкретными для роли значениями. +- **BR-3** — Few-shot: каждый промпт ссылается на скелеты 52b (`docs/_templates/`) и эталоны + (ORCH-073 / ORCH-088); запреты сопровождаются позитивным примером («делай Y вместо X»). +- **BR-4 (АНТИ-РЕГРЕСС, критично для self-hosting)** — НИ ОДНА функциональная инструкция + старого промпта не потеряна: гейты, machine-verdict ключи и их регистр, маркеры `ORCH-NNN`, + правила `CLAUDE.md`, ролевые запреты, идемпотентный merge-guard, canonical staging-команда + (`docker exec`), self-hosting-запреты. Агенты продолжают проходить свои гейты. +- **BR-5** — Код НЕ изменён: правятся только `.openclaw/agents/*.md` + документация; + `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` нетронуты. +- **BR-6** — Проведена A/B-проверка минимум на одной репрезентативной стадии (старый vs новый + промпт): новый промпт НЕ хуже по числу циклов `REQUEST_CHANGES` / качеству артефакта. +- **BR-7** — Документация (`CLAUDE.md` / `README` / ADR / `CHANGELOG`) обновлена в том же PR. + +## 5. Нефункциональные требования (NFR) + +- **NFR-1 (обратная совместимость гейтов)** — Новые промпты эмитят схему **аддитивно**: рядом с + существующими machine-verdict ключами, не меняя их имени/регистра/позиции. Гейты читают вердикты + ровно как раньше (схема при `strict=False` в вердикте не участвует). +- **NFR-2 (безопасность прода)** — Промпт = поведение агента прода для ВСЕХ проектов. Рефактор + формы не должен ослабить ни одну рабочую инструкцию (особенно self-hosting-запреты deployer'а: + «не рестартить 8500 изнутри», merge-guard). +- **NFR-3 (валидность frontmatter промпта)** — YAML-frontmatter каждого `.openclaw/agents/*.md` + остаётся валидным YAML, сохраняет `name`/`description`, НЕ возвращает удалённый `model:` + (тест `test_agent_frontmatter_no_model.py` остаётся зелёным). +- **NFR-4 (читабельность/сопровождаемость)** — Единый канон облегчает будущие правки; объём + каждого промпта остаётся соразмерным (без раздувания «воды»). +- **NFR-5 (обратимость)** — Изменение чисто текстовое; откат = git revert PR, без миграций + состояния/БД. + +## 6. Допущения и ограничения + +- **Допущение 1** — `model_used` для всех 6 ролей сейчас = `claude-opus-4-8` (README §«Модель и + эффорт по ролям»); промпт инструктирует ставить именно эту модель как резолв ORCH-41. Если + model-routing включат позже — значение пересматривается, но это вне ORCH-077. +- **Допущение 2** — `created_at` агент берёт как текущую дату (`YYYY-MM-DD`); источник — + доступный агенту способ (напр. `date +%F` через Bash там, где Bash в `tools:`). +- **Ограничение 1** — `tools:`-блок и разрешённые пути записи каждого промпта НЕ расширяются: + агент эмитит схему только в те документы, которые и так авторствует. +- **Ограничение 2** — Developer не авторствует номерного handoff-вердикт-документа (его выход — + код + PR, гейт `check_ci_green`); для него инструкция схемы применяется к when-applicable + докам (`07`/`08`/`10`), если он их трогает, а основной акцент — на сохранении dev-инструкций. +- **Ограничение 3** — `frontmatter_validation_strict` остаётся `False`; ORCH-077 НЕ включает + hard-fail (это была бы правка config = вне scope). + +## 7. Критерии успеха + +Резюме: 6 промптов переписаны по канону Anthropic, эмитят схему 52c, не потеряли ни одной +функциональной инструкции, код не тронут, документация обновлена, A/B подтверждает «не хуже». +Детальные PASS/FAIL — `03-acceptance-criteria.md`. + +## 8. Риски + +Краткий перечень (детали — `10-tech-risks.md`, заполняет архитектор): + +- **R-1 (регресс поведения агента)** — при рефакторе формы потерять рабочую инструкцию → + агент ломает выход для ВСЕХ проектов. Митигация: построчная карта «старая инструкция → где в + новом промпте» (AC-4), A/B-прогон. +- **R-2 (ложный гейт-провал)** — случайно изменить регистр/имя machine-verdict ключа или + сместить его так, что парсер не найдёт. Митигация: явный инвентарь ключей, структурные тесты. +- **R-3 (некорректный `model_used`)** — захардкодить неверную модель. Митигация: ссылка на + резолв ORCH-41 и таблицу README. +- **R-4 (раздувание промпта)** — XML-канон + few-shot увеличат объём и «утопят» ключевые + запреты. Митигация: ссылки на эталоны вместо инлайна, контроль объёма. diff --git a/docs/work-items/ORCH-077/02-trz.md b/docs/work-items/ORCH-077/02-trz.md new file mode 100644 index 0000000..ed17fe7 --- /dev/null +++ b/docs/work-items/ORCH-077/02-trz.md @@ -0,0 +1,227 @@ +# 02 — ТЗ (TRZ): ORCH-077 — ORCH-52d: оптимизация 6 системных промптов по Anthropic + +Work Item: **ORCH-077** · Repo: **orchestrator** (self-hosting) · Стадия: analysis + +> ТЗ описывает **конкретные изменения** (выведенные из BRD и фактического содержимого репозитория). +> Архитектурное обоснование (порядок секций, формулировки, нужен ли сквозной ADR) — задача +> архитектора (`06-adr`). Это **docs/prompts-only** задача: код не меняется. + +## 1. Сводка изменения + +Переписать 6 системных промптов агентов (`.openclaw/agents/*.md`) в едином каноне Anthropic +(XML-секции) и научить каждый эмитить обязательную frontmatter-схему 52c в авторских документах. +**Тело** промпта (Markdown ниже frontmatter) реструктурируется; **YAML-frontmatter промпта** +(`name`, `description`, `tools`) сохраняется как есть (без `model:`). СОДЕРЖАНИЕ всех +функциональных требований переносится 1:1 (см. §3 — инвентарь анти-регресса). Параллельно +обновляется документация (§8). + +## 2. Задействованные модули / пути + +| Путь | Действие | +|------|----------| +| `.openclaw/agents/analyst.md` | переписать (тело) | +| `.openclaw/agents/architect.md` | переписать (тело) | +| `.openclaw/agents/developer.md` | переписать (тело) | +| `.openclaw/agents/reviewer.md` | переписать (тело) | +| `.openclaw/agents/tester.md` | переписать (тело) | +| `.openclaw/agents/deployer.md` | переписать (тело) | +| `CLAUDE.md` | обновить (раздел про промпты / эпик 52) | +| `docs/architecture/README.md` | обновить (раздел про схему/handoff и слой промптов 52d) | +| `docs/work-items/ORCH-077/06-adr/ADR-001-*.md` | создать (архитектор) | +| `docs/architecture/adr/adr-NNNN-*.md` | создать при необходимости (архитектор, если сквозное) | +| `CHANGELOG.md` | добавить запись `## [Unreleased]` | +| `tests/test_agent_prompts_canon.py` (имя — на усмотрение dev) | создать (структурные тесты, §7 / см. test-plan) | +| **НЕ трогать** | `src/**` (любой), включая `config.py`, `agents/launcher.py`, `frontmatter.py`, `stages.py`, `qg/checks.py`, `stage_engine.py` | + +## 3. Функциональные требования + +### FR-1 — Единая XML-структура секций во всех 6 промптах (BR-1) + +Тело каждого промпта организовано вокруг секций (XML-теги как разделители смысловых блоков): + +- `` — кто агент, проект orchestrator, стек, self-hosting, что прочесть перед работой + (обязательный пункт «прочти `CLAUDE.md` и `docs/architecture/README.md`»). +- `` — что делает роль на своей стадии; допускается вложенная ``-подсказка + (явное место для рассуждения, где уместно — FR-4). +- `` — какие файлы и куда роль создаёт через Write tool. +- `` — запреты и обязательные правила (включая ролевые «Запрещено» из старых промптов). +- `` — точный формат выходных документов, включая frontmatter-схему (FR-2) и + machine-verdict ключи. + +Дополнительные секции допустимы (напр. ``, ``), но 5 перечисленных +обязательны во всех 6 промптах. + +### FR-2 — Инструкция эмитить обязательную frontmatter-схему 52c (BR-2) + +В секции `` каждого промпта явно перечислены 6 обязательных полей схемы +(`src/frontmatter.py::REQUIRED_FIELDS`) с конкретными для роли значениями. Схема ставится +**аддитивно** — ПОВЕРХ существующих ключей документа, НЕ заменяя и НЕ смещая machine-verdict +ключи (NFR-1). + +| Поле | Значение / источник | +|------|---------------------| +| `work_item` | ID задачи (`ORCH-NNN` / `ET-NNN`) — подставляется агентом | +| `stage` | стадия роли (см. таблицу ниже) | +| `author_agent` | роль (см. таблицу ниже) | +| `status` | статус выхода стадии (роле-специфично; для вердикт-доков согласован с вердиктом) | +| `created_at` | текущая дата `YYYY-MM-DD` | +| `model_used` | резолв ORCH-41 — на текущий момент `claude-opus-4-8` для всех ролей (README §«Модель и эффорт») | + +**Карта роль → стадия → author_agent → документы, несущие схему:** + +| Роль (prompt) | `stage` | `author_agent` | Документы со схемой | Machine-verdict ключ (НЕ трогать) | +|---------------|---------|----------------|---------------------|-----------------------------------| +| analyst | `analysis` | `analyst` | `01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`, `04-test-plan.yaml` | — (нет; гейт = наличие файлов + Approved) | +| architect | `architecture` | `architect` | `06-adr/ADR-NNN-*.md`, `07-infra-requirements.md`, `08-data-requirements.md`, `10-tech-risks.md` | — | +| developer | `development` | `developer` | when-applicable доки, если трогает (`07`/`08`/`10`); код/PR номерного вердикт-дока не несёт | — (гейт = `check_ci_green`) | +| reviewer | `review` | `reviewer` | `12-review.md` | `verdict:` (`APPROVED`\|`REQUEST_CHANGES`) | +| tester | `testing` | `tester` | `13-test-report.md` | `result:`/`verdict:`/`status:` (`PASS`\|`FAIL`\|`BLOCKED`) | +| deployer | `deploy-staging`, `deploy` | `deployer` | `15-staging-log.md`, `14-deploy-log.md`, `17-security-report.md` (when-applicable) | `staging_status:`, `deploy_status:`, `security_status:` | + +> Примечание по `04-test-plan.yaml`: это YAML-документ (не Markdown с frontmatter-блоком). Схема +> ложится как top-level ключи YAML рядом с существующими (`work_item` уже присутствует в скелете; +> добавляются `stage`/`author_agent`/`status`/`created_at`/`model_used`). Архитектор фиксирует +> точную форму в ADR, если есть нюанс совместимости со скелетом 52b. + +### FR-3 — Few-shot и позитивные примеры (BR-3) + +В каждом промпте (секция `` и/или ``): + +- ссылка на копируемый скелет роли в `docs/_templates/` (напр. analyst → `01-brd.md`, + `02-trz.md`, `03-acceptance-criteria.md`, `04-test-plan.yaml`); +- ссылка на эталонный заполненный work item — **ORCH-073** и/или **ORCH-088** — как пример + качества/полноты; +- каждый запрет в `` сопровождается позитивной альтернативой: формат + «❌ не делай X → ✅ делай Y» (литеральность Opus 4.8). + +### FR-4 — Явное место для рассуждения (CoT/thinking) + +Там, где роль принимает решение (architect — выбор решения; reviewer — вынесение вердикта; +tester — классификация PASS/FAIL/BLOCKED; deployer — трактовка exit-кодов/waiver), промпт +содержит явную ``-подсказку «сначала рассуди, потом пиши вердикт». Для механических +ролей (минимально) — не обязательно. + +### FR-5 — Success-criteria артефакта стадии + +В каждом промпте есть явный блок «выход считается готовым, когда…»: перечень файлов + наличие +обязательных frontmatter-полей + (для вердикт-ролей) корректный machine-verdict ключ. + +### FR-6 — АНТИ-РЕГРЕСС: инвентарь сохраняемых инструкций (BR-4, критично) + +Ниже — обязательный к переносу 1:1 минимум по каждому промпту. Reviewer проверяет ПОСТРОЧНО. +Список не исчерпывающий: переносится ВСЁ функциональное содержание, перечисленное — обязательный +костяк. + +**analyst.md:** +- «Используй Write tool; не выводи содержимое в stdout». +- Список «что прочесть» (`CLAUDE.md`, README, `00-business-request.md`, `src/`). +- 4 обязательных deliverable: `01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`, + `04-test-plan.yaml`. +- Формат TRZ (модули `src/`, изменения API, изменения БД, требования к QG, артефакты pipeline). +- Формат `test-plan.yaml` (id/type/description/module/expected). +- Запреты: не предлагать архитектурные решения, не писать код, не править чужие work item, не + выводить в stdout. + +**architect.md:** +- «Прочти CLAUDE.md и README». +- Контекст стека, конвейер, self-hosting-предупреждение (общий прод-контейнер). +- Deliverables: `06-adr/ADR-NNN-*.md` (обяз.), `07`/`08`/`10` (по применимости). +- Правило сквозного ADR `docs/architecture/adr/adr-NNNN-*` для сквозных решений. +- ADR-формат (Статус / Контекст / Решение / Последствия). +- «Документация = golden source»: обновлять README/internals при изменении стадий/QG. +- Self-hosting-запреты: не предлагать рестарт прода без staging-гейта, всё ORCH — через 8501. +- Принципы (Docker/один сервер, SQLite, conventional/trunk, без k8s/облака, без ORM при raw SQL). +- Запреты (multi-node/managed, лишний MQ, менять QG без ADR, рестарт прода без staging). +- Эскалация (`arch:major-change`, `back-to:analysis`). + +**developer.md:** +- «Прочти CLAUDE.md и README». +- Стек, список «что прочесть» (`02-trz` — источник правды, `03`, `04`, `06-adr/`, код). +- Алгоритм: fetch+rebase origin/main → TDD (тест, потом код) → миграции при смене схемы → + `ruff check` + `pytest` → conventional commit (`Refs: `) → push → PR в Gitea. +- «Документация = golden source в ТОМ ЖЕ PR» (API/конвейер/конфиг/компонент/CHANGELOG). +- Конвенции (conventional commits, ветки, docstring, содержательные тесты). +- Self-hosting: НЕ перезапускать прод, проверять через `pytest` локально. +- Запреты: не менять ТЗ/ADR, без ADR не решать архитектуру, не коммитить секреты, + PR > 1500 строк без декомпозиции, не мержить свой PR, без `--no-verify`/`--force-push`, + не рестартить прод. + +**reviewer.md:** +- «Прочти CLAUDE.md (правила документирования!) и README». +- 4 оси: соответствие ТЗ, соответствие ADR, качество кода, **качество документации**. +- Жёсткое правило: src/ изменён, а `docs/`/`CHANGELOG`/ADR НЕ обновлены → ОБЯЗАТЕЛЬНО + `REQUEST_CHANGES` (приоритет над остальным). +- Severity P0/P1/P2/P3 (с пунктом «документация не обновлена при изменении src/» = P0). +- Правило вердикта: любой P0/P1 → `REQUEST_CHANGES`; только P2/P3 / нет findings → `APPROVED`. +- **Frontmatter-контракт `12-review.md`:** вердикт читается ТОЛЬКО из `verdict:` (UPPERCASE, + строго `APPROVED`|`REQUEST_CHANGES`), упоминания в прозе не учитываются; без frontmatter → + not-approved. +- Запреты: не править код, не апрувить PR того же экземпляра developer, без subjective без + ссылки на правило, не пропускать проверку документации. + +**tester.md:** +- «Прочти CLAUDE.md и README». +- Что прочесть (`02`/`03`/`04`/`12-review.md` — убедиться, что вердикт APPROVED). +- Алгоритм: проверка окружения (`curl /health`) → `pytest tests/ -v --tb=short` → smoke API + (`/health`, `/status`, `/queue`) → сверка покрытия ТЗ с `04-test-plan.yaml` и `03`. +- **Frontmatter `13-test-report.md`:** `result:` (PASS|FAIL) — машинный вердикт; таблица TC, + вывод pytest, итог. +- Вердикт: все PASS+smoke OK → `result: PASS` → deploy-staging; любой FAIL → `result: FAIL` → + откат на development. +- Запреты: не писать прод-код, не подгонять тесты под код, не запускать деструктив на проде. + +**deployer.md** (наиболее рискованный — self-hosting): +- Шапка-предупреждение: прочесть CLAUDE.md/README/INFRA.md; **НЕ перезапускать прод 8500**. +- Стадия `deploy-staging`: canonical-команда `docker exec orchestrator-staging python3 + /repos/orchestrator/scripts/staging_check.py --base-url http://localhost:8501 --mode stub` + (с обоснованием B6 registry-isolation — сохранить!); маппинг exit 0 → `SUCCESS`, ≠0 → `FAILED`. +- ORCH-061: толерантность к waived C9a/C9b (`INFRA-WAIVED:` копировать в лог; доверять exit-коду, + не пересуживать); kill-switch `ORCH_STAGING_INFRA_TOLERANCE_ENABLED=false`/`--strict`. +- `staging_status:` строго `SUCCESS`|`FAILED` (UPPERCASE) — единственный машинный ключ + `check_staging_status`. +- Merge `15-staging-log.md` в `main` (commit+push). +- Стадия `deploy`: контракт `deploy_status: SUCCESS|FAILED` (читает только `check_deploy_status`). +- **Идемпотентный merge-guard (ORCH-065):** перед (повторным) merge feature-PR в `main` + консультировать `merge_gate.pr_already_merged(repo, branch)`; MERGED=1 → не мержить повторно + (no-op), MERGED=0 → мержить; guard never-raise. +- **Self-hosting (`orchestrator`):** ты НЕ деплоишь себя; Phase A/B/C оркестрируются кодом + (`stage_engine`/`self_deploy`); НИКОГДА не запускать `docker compose up -d orchestrator` / + `--build` / рестарт 8500 изнутри; `deploy_status: SUCCESS` = реальный host health-ok. +- Non-self репо (enduro): прежний синхронный ssh-деплой через + `scripts/orchestrator-deploy-hook.sh`. +- Общие правила: всегда машинный YAML-frontmatter (гейты парсят только frontmatter); никогда + push в `main` напрямую; не менять `.env`/`.env.staging`/`docker-compose.yml`/прод-инфру. + +### FR-7 — Валидность frontmatter промптов (NFR-3) + +YAML-frontmatter каждого `.openclaw/agents/*.md` остаётся валидным YAML, сохраняет +`name`==роль и непустой `description`, и НЕ содержит ключа `model:` +(`tests/test_agent_frontmatter_no_model.py` остаётся зелёным). + +## 4. Изменения API + +Нет. Эндпоинты не добавляются/не меняются. + +## 5. Изменения схемы БД + +Нет. Миграции/таблицы/индексы не трогаются. + +## 6. Требования к новым/изменённым QG checks + +Нет. `QG_CHECKS`, `check_*`, `_parse_*`, `STAGE_TRANSITIONS` — без изменений. +`frontmatter_validation_strict` остаётся `False` (warning-only) — hard-fail НЕ включается. + +## 7. Совместимость / регресс + +- **Обратная совместимость гейтов:** схема эмитится аддитивно; machine-verdict ключи (имя, + регистр) неизменны → все 5 вердикт-парсеров читают как раньше (NFR-1). +- **Без kill-switch:** изменение чисто текстовое (промпты + доки); поведение кода идентично. +- **Обратимость:** `git revert` PR; нет миграций/состояния. +- **Тесты:** добавляются структурные тесты промптов (присутствие 5 XML-секций; присутствие + инструкции по 6 полям схемы; присутствие сохранённых machine-verdict ключей и ключевых + маркеров анти-регресса). Существующий `test_agent_frontmatter_no_model.py` остаётся зелёным; + полный `pytest tests/ -q` — зелёный. +- **A/B (BR-6):** на ≥1 репрезентативной стадии сравнить выход старого vs нового промпта; + критерий — новый не увеличивает число циклов `REQUEST_CHANGES` и не теряет содержания + артефакта. Метод фиксирует архитектор/исполнитель (напр. прогон одной стадии в staging / + ручное сравнение артефактов на эталонной задаче). diff --git a/docs/work-items/ORCH-077/03-acceptance-criteria.md b/docs/work-items/ORCH-077/03-acceptance-criteria.md new file mode 100644 index 0000000..4f5b3cf --- /dev/null +++ b/docs/work-items/ORCH-077/03-acceptance-criteria.md @@ -0,0 +1,133 @@ +# 03 — Критерии приёмки (Acceptance Criteria): ORCH-077 — ORCH-52d: оптимизация 6 системных промптов по Anthropic + +Work Item: **ORCH-077** · Repo: **orchestrator** (self-hosting) · Стадия: analysis + +Формат: каждый критерий имеет **PASS** (что должно быть истинно для приёмки) и **FAIL** +(что считается провалом). Reviewer/tester проверяют их буквально по файлам репозитория. + +--- + +## AC-1 — Единый XML-стиль во всех 6 промптах + +**Условие:** Все 6 файлов `.openclaw/agents/{analyst,architect,developer,reviewer,tester,deployer}.md` +переписаны единым каноном с XML-секциями. +- **PASS:** Тело каждого из 6 промптов содержит все 5 обязательных секций-тегов: ``, + ``, ``, ``, `` (открывающий и закрывающий тег). +- **FAIL:** Хотя бы в одном промпте отсутствует одна из 5 секций, ИЛИ структура осталась прежней + свободной формой без XML-разметки. + +--- + +## AC-2 — Инструкция эмитить обязательную frontmatter-схему 52c + +**Условие:** Каждый промпт явно инструктирует агента проставлять 6 обязательных полей схемы +(`work_item`, `stage`, `author_agent`, `status`, `created_at`, `model_used`) в авторских документах. +- **PASS:** В секции `` каждого из 6 промптов перечислены ВСЕ 6 имён полей схемы; + для роли указаны конкретные значения `stage` (стадия роли) и `author_agent` (роль) согласно + карте TRZ §FR-2; `model_used` привязан к резолву ORCH-41 (`claude-opus-4-8`). +- **FAIL:** В любом промпте отсутствует хотя бы одно из 6 имён полей, ИЛИ `author_agent`/`stage` + не конкретизированы для роли, ИЛИ инструкция отсутствует вовсе. + +--- + +## AC-3 — Few-shot и позитивные примеры рядом с запретами + +**Условие:** Каждый промпт ссылается на скелеты 52b и эталоны, запреты имеют позитивную альтернативу. +- **PASS:** Каждый из 6 промптов содержит (а) ссылку на `docs/_templates/` для своих документов; + (б) ссылку хотя бы на один эталонный work item (`ORCH-073` или `ORCH-088`); (в) минимум один + запрет, оформленный с позитивной альтернативой («делай Y вместо X» / «❌ … → ✅ …»). +- **FAIL:** В любом промпте нет ссылки на шаблоны, ИЛИ нет ссылки на эталон, ИЛИ запреты поданы + только негативно (без позитивной альтернативы ни в одном пункте). + +--- + +## AC-4 — АНТИ-РЕГРЕСС: ни одна функциональная инструкция не потеряна + +**Условие:** Все функциональные инструкции старых промптов перенесены в новые (инвентарь TRZ §FR-6). +- **PASS:** Для каждого промпта присутствуют все ключевые элементы инвентаря §FR-6, в частности + (минимальный машинно-проверяемый набор): + - **reviewer.md** содержит machine-key `verdict:` со значениями `APPROVED`|`REQUEST_CHANGES` + (UPPERCASE) и правило «вердикт читается только из frontmatter»; правило «src/ изменён, доки нет + → REQUEST_CHANGES». + - **tester.md** содержит `result:` со значениями `PASS`|`FAIL` как машинный вердикт; алгоритм + pytest + smoke (`/health`,`/status`,`/queue`). + - **deployer.md** содержит `staging_status:` (`SUCCESS`|`FAILED`), `deploy_status:` + (`SUCCESS`|`FAILED`), canonical `docker exec orchestrator-staging … staging_check.py`, + идемпотентный merge-guard `pr_already_merged`, self-hosting-запрет «не рестартить 8500 изнутри», + ORCH-061 waiver-логику. + - **analyst.md** содержит 4 deliverable (`01`/`02`/`03`/`04`), «использовать Write tool», формат + TRZ и test-plan. + - **architect.md** содержит ADR-формат, правило сквозного ADR, self-hosting-запрет «без рестарта + прода без staging», эскалацию. + - **developer.md** содержит TDD-алгоритм, «документация в том же PR», запреты (не мержить свой PR, + без `--no-verify`/`--force-push`, не рестартить прод, не коммитить секреты). +- **FAIL:** Любой элемент инвентаря §FR-6 отсутствует или искажён (изменён регистр/имя + machine-verdict ключа; пропал self-hosting-запрет; пропал merge-guard; пропала canonical-команда). + +--- + +## AC-5 — Код не изменён, гейты нетронуты + +**Условие:** Правятся только `.openclaw/agents/*.md` + документация; код и контракты гейтов не тронуты. +- **PASS:** `git diff` затрагивает ТОЛЬКО `.openclaw/agents/*.md`, `CLAUDE.md`, + `docs/**`, `CHANGELOG.md` и (новые) `tests/test_*prompt*`/`tests/test_*canon*`. Файлы + `src/config.py`, `src/agents/launcher.py`, `src/frontmatter.py`, `src/stages.py`, + `src/qg/checks.py`, `src/stage_engine.py` НЕ изменены. `frontmatter_validation_strict` остаётся + `False`. +- **FAIL:** Изменён любой файл `src/**`, ИЛИ затронут `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`, ИЛИ + включён hard-fail валидации схемы. + +--- + +## AC-6 — A/B-проверка на репрезентативной стадии: «не хуже» + +**Условие:** Проведено сравнение старого vs нового промпта минимум на одной стадии. +- **PASS:** В артефактах задачи (`13-test-report.md` и/или ADR/`12-review.md`) зафиксирован + результат A/B: новый промпт даёт артефакт не хуже старого — число циклов `REQUEST_CHANGES` не + выросло, обязательные элементы артефакта присутствуют, машинный вердикт корректно парсится. +- **FAIL:** A/B не проводилось/не зафиксировано, ИЛИ новый промпт показал регресс (больше циклов + REQUEST_CHANGES, потеря содержания, непарсимый вердикт). + +--- + +## AC-7 — Документация обновлена + +**Условие:** `CLAUDE.md`, `docs/architecture/README.md`, ADR и `CHANGELOG.md` обновлены в том же PR. +- **PASS:** Есть per-work-item ADR `docs/work-items/ORCH-077/06-adr/ADR-001-*.md`; `CLAUDE.md` и + `docs/architecture/README.md` отражают слой промптов 52d (эмиссия схемы); `CHANGELOG.md` содержит + запись под `## [Unreleased]`. +- **FAIL:** Отсутствует ADR, ИЛИ README/CLAUDE.md не упоминают 52d-изменение, ИЛИ нет записи в + CHANGELOG. + +--- + +## AC-8 — Валидность frontmatter промптов сохранена + +**Условие:** YAML-frontmatter каждого промпта валиден и не возвращает `model:`. +- **PASS:** `tests/test_agent_frontmatter_no_model.py` зелёный: каждый frontmatter парсится как + YAML-mapping, `name`==роль, `description` непуст, ключа `model:` нет. +- **FAIL:** Любой промпт сломал YAML-frontmatter, потерял `name`/`description`, ИЛИ вернул `model:`. + +--- + +## AC-9 — Полный регресс тестов зелёный + +**Условие:** Изменение не ломает существующий набор тестов. +- **PASS:** `pytest tests/ -q` зелёный; новые структурные тесты промптов проходят. +- **FAIL:** Любой тест падает. + +--- + +## Сводная матрица AC ↔ FR/BR + +| AC | Покрывает | +|----|-----------| +| AC-1 | BR-1 / FR-1 | +| AC-2 | BR-2 / FR-2 | +| AC-3 | BR-3 / FR-3 | +| AC-4 | BR-4 / FR-6 / NFR-2 | +| AC-5 | BR-5 / TRZ §4–§6 | +| AC-6 | BR-6 / FR-7(A/B) | +| AC-7 | BR-7 | +| AC-8 | NFR-3 / FR-7 | +| AC-9 | NFR-1 / TRZ §7 | diff --git a/docs/work-items/ORCH-077/04-test-plan.yaml b/docs/work-items/ORCH-077/04-test-plan.yaml new file mode 100644 index 0000000..c7a34b7 --- /dev/null +++ b/docs/work-items/ORCH-077/04-test-plan.yaml @@ -0,0 +1,77 @@ +work_item: ORCH-077 +title: "ORCH-52d — канон Anthropic + эмиссия frontmatter-схемы в 6 промптах агентов" +framework: pytest +scope: > + Структурная верификация 6 системных промптов (.openclaw/agents/*.md): наличие XML-секций, + инструкции эмитить обязательную frontmatter-схему 52c, сохранение machine-verdict ключей и + ключевых анти-регресс маркеров, валидность YAML-frontmatter. Вне покрытия: семантическое + качество выхода агентов (оценивается A/B-проверкой вручную, TC-09) и любая логика src/ + (код не меняется). +notes: > + Задача docs/prompts-only — src/ не трогается. Тесты читают файлы .openclaw/agents/*.md как + текст/YAML. Существующий tests/test_agent_frontmatter_no_model.py (ORCH-074) ОБЯЗАН остаться + зелёным. Полный регресс pytest tests/ -q должен оставаться зелёным. Имена тест-функций/файла — + ориентир; точную реализацию определяет developer (например tests/test_agent_prompts_canon.py). + Списки обязательных секций/полей/ключей вынести в параметризацию, чтобы тест шёл по всем 6 + ролям единообразно. + +tests: + - id: TC-01 + type: unit + description: "Каждый из 6 промптов содержит все 5 XML-секций (////), открывающий и закрывающий тег. (AC-1)" + module: tests/test_agent_prompts_canon.py + expected: PASS + + - id: TC-02 + type: unit + description: "Каждый промпт перечисляет все 6 имён полей схемы 52c (work_item/stage/author_agent/status/created_at/model_used) в теле. (AC-2)" + module: tests/test_agent_prompts_canon.py + expected: PASS + + - id: TC-03 + type: unit + description: "Для каждой роли в промпте присутствуют корректные конкретные значения author_agent (==роль) и stage (стадия роли по карте FR-2). (AC-2)" + module: tests/test_agent_prompts_canon.py + expected: PASS + + - id: TC-04 + type: unit + description: "Каждый промпт ссылается на docs/_templates/ и хотя бы на один эталон (ORCH-073 или ORCH-088). (AC-3)" + module: tests/test_agent_prompts_canon.py + expected: PASS + + - id: TC-05 + type: unit + description: "АНТИ-РЕГРЕСС machine-verdict ключей: reviewer.md содержит 'verdict:' (APPROVED|REQUEST_CHANGES), tester.md — 'result:' (PASS|FAIL), deployer.md — 'staging_status:' и 'deploy_status:' (SUCCESS|FAILED), регистр сохранён. (AC-4)" + module: tests/test_agent_prompts_canon.py + expected: PASS + + - id: TC-06 + type: unit + description: "АНТИ-РЕГРЕСС deployer self-hosting: deployer.md содержит canonical 'docker exec orchestrator-staging' staging-команду, merge-guard 'pr_already_merged', запрет рестарта 8500 изнутри, ORCH-061 'INFRA-WAIVED'. (AC-4)" + module: tests/test_agent_prompts_canon.py + expected: PASS + + - id: TC-07 + type: unit + description: "АНТИ-РЕГРЕСС ключевых маркеров остальных ролей: analyst — 4 deliverable + Write tool; architect — ADR-формат + сквозной ADR + эскалация; developer — TDD + 'не мержить свой PR' + 'не рестартить прод'; reviewer — правило 'src изменён, доки нет → REQUEST_CHANGES'. (AC-4)" + module: tests/test_agent_prompts_canon.py + expected: PASS + + - id: TC-08 + type: unit + description: "Валидность frontmatter промптов: каждый .openclaw/agents/*.md парсится как YAML-mapping, name==роль, description непуст, ключа 'model:' нет (re-use существующего теста ORCH-074). (AC-8)" + module: tests/test_agent_frontmatter_no_model.py + expected: PASS + + - id: TC-09 + type: integration + description: "A/B-проверка на репрезентативной стадии (старый vs новый промпт): новый не хуже по числу циклов REQUEST_CHANGES и полноте артефакта; вердикт корректно парсится. Ручной/полуавтоматический прогон; результат фиксируется в 13-test-report.md. (AC-6)" + module: tests/manual/ab_prompt_compare.md + expected: PASS + + - id: TC-10 + type: integration + description: "Полный регресс: pytest tests/ -q зелёный (код не тронут, гейты и контракты целы). (AC-9)" + module: tests/ + expected: PASS