160 lines
14 KiB
Markdown
160 lines
14 KiB
Markdown
---
|
||
work_item: ORCH-092
|
||
stage: analysis
|
||
author_agent: analyst
|
||
status: ready-for-review
|
||
created_at: 2026-06-09
|
||
model_used: claude-opus-4-8
|
||
---
|
||
|
||
# 02 — ТЗ (TRZ): ORCH-092 — Промпт-аудит 6 агентов
|
||
|
||
Work Item: **ORCH-092** · Repo: **orchestrator** · Стадия: analysis
|
||
|
||
> ТЗ описывает **конкретные изменения к реализации**, выведенные из BRD и фактического кода.
|
||
> Архитектурное обоснование/решения (P1-2 rebase, P2-2 язык deployer) — задача архитектора (`06-adr/`).
|
||
|
||
## 1. Сводка изменения
|
||
|
||
Точечная правка 6 системных промптов `.openclaw/agents/*.md` + обзорной документации + структурных
|
||
анти-регресс-тестов. **Код приложения не трогается** (docs/prompts-only). Цель — устранить класс
|
||
дефектов промптов (хардкод даты/модели, размазанная эскалация, нереализуемые/конфликтующие
|
||
инструкции, мёртвые инструкции, недообогащённые промпты), сохранив канон 52d/52c/52e и
|
||
машинные verdict-ключи байт-в-байт.
|
||
|
||
## 2. Задействованные модули / пути
|
||
|
||
| Путь | Действие |
|
||
|------|----------|
|
||
| `.openclaw/agents/analyst.md` | изменить — расхардкод `created_at`/`model_used` в примере (FR-1, FR-2) |
|
||
| `.openclaw/agents/architect.md` | изменить — расхардкод `created_at`/`model_used` в примере (FR-1, FR-2) |
|
||
| `.openclaw/agents/developer.md` | изменить — расхардкод (FR-1/2); «PR>1500»→эскалация (FR-4); `<escalation>` (FR-5); rebase по решению ADR (FR-9) |
|
||
| `.openclaw/agents/reviewer.md` | изменить — расхардкод (FR-1/2); `<escalation>` (FR-5); удалить мёртвую инструкцию (FR-8) |
|
||
| `.openclaw/agents/tester.md` | изменить — расхардкод (FR-1/2); `<escalation>` (FR-5); worktree-путь + serial_gate smoke + покрытие ТЗ (FR-7) |
|
||
| `.openclaw/agents/deployer.md` | изменить — расхардкод (FR-1/2); рамка критичных запретов (FR-6); язык по решению ADR (FR-10) |
|
||
| `tests/test_agent_prompts_canon.py` | изменить — добавить TC анти-регресса новых инвариантов (FR-11) |
|
||
| `CLAUDE.md` | изменить — отразить ORCH-092 (норматив промптов), при необходимости |
|
||
| `docs/architecture/README.md` | изменить — when-applicable (если затрагивается обзорная карта) |
|
||
| `CHANGELOG.md` | изменить — запись под `## [Unreleased]` |
|
||
| `docs/work-items/ORCH-092/06-adr/ADR-001-*.md` | создать (архитектор) — решения P1-2, P2-2 |
|
||
| `src/**`, `src/qg/checks.py`, `STAGE_TRANSITIONS`, `QG_CHECKS`, схема БД | **НЕ трогать** |
|
||
|
||
## 3. Функциональные требования
|
||
|
||
### FR-1 — Расхардкод `created_at` в примерах (BR-1, P0-1)
|
||
Во **всех 6** промптах в копируемом примере frontmatter заменить `created_at: 2026-06-09` на
|
||
плейсхолдер `created_at: <YYYY-MM-DD>`. Рядом — явная инструкция (в `<output_format>`): «подставь
|
||
фактическую текущую дату (`date +%F`); НЕ копируй дату из примера буквально». Инвариант: имя поля
|
||
`created_at` остаётся (канон-тест проверяет наличие имени).
|
||
|
||
### FR-2 — Расхардкод `model_used` в примерах (BR-2, P0-2)
|
||
Во **всех 6** промптах в копируемом примере заменить `model_used: claude-opus-4-8` на
|
||
`model_used: <resolve ORCH-41>` + оговорку «подставь фактическую модель из конфига, не копируй
|
||
буквально». Факт «сейчас `claude-opus-4-8`» допустимо оставить как **справку в таблице полей**
|
||
(вне копируемого блока). Инвариант: имя поля `model_used` остаётся.
|
||
|
||
### FR-3 — Сверка имён гейтов с `QG_CHECKS` (BR-3, P0-3)
|
||
Пройти по каждому промпту, сверить все упомянутые `check_*`/имена QG-функций с реальным реестром
|
||
`QG_CHECKS` в `src/qg/checks.py`. **Установленный факт:** на момент анализа несовпадений НЕТ
|
||
(`check_ci_green`, `check_reviewer_verdict`, `check_tests_passed`, `check_deploy_status`,
|
||
`check_staging_status`, `check_security_gate` — все присутствуют в реестре; `check_tests_passed`
|
||
верен — подозрение было ложным). Требование: **исправлять только реально несовпадающие** имена
|
||
(не выдумывать); закрепить сверку воспроизводимым тестом (FR-11/TC-03).
|
||
|
||
### FR-4 — «PR>1500» → эскалация (BR-4, P1-1)
|
||
В `developer.md` (секция `<constraints>`) заменить запрет «❌ Не делай PR > 1500 строк без
|
||
декомпозиции → ✅ разбивай на меньшие PR» на эскалацию: PR оказался слишком большим → **флагируй/
|
||
эскалируй** (задача слишком крупная, нужна декомпозиция **на уровне задач**, не внутри стадии;
|
||
1 задача = 1 ветка = 1 PR). Инвариант FR-6-анти-регресс: маркер «свой PR» («не мержи свой PR»)
|
||
сохраняется отдельно.
|
||
|
||
### FR-5 — Секция `<escalation>` в developer/reviewer/tester (BR-5, P1-3)
|
||
Добавить секцию `<escalation>` (формат — как у `architect.md`, **после** `</success_criteria>`,
|
||
чтобы не нарушать нормативный порядок 5 обязательных секций):
|
||
- **developer:** негодное/нереализуемое ТЗ → вернуть в Анализ (`back-to:analysis`); нужна новая
|
||
архитектурная развилка → эскалация к архитектору.
|
||
- **tester:** обоснованный FAIL → откат на development (`back-to:dev`); смок-сбой инфраструктуры →
|
||
зафиксировать как FAIL с диагностикой.
|
||
- **reviewer:** любой P0/P1 → `REQUEST_CHANGES` (единая точка); неоднозначность требований →
|
||
finding со ссылкой на ТЗ/ADR.
|
||
|
||
Эскалационные строки консолидируют (не дублируют слепо) то, что было размазано по `<constraints>`.
|
||
|
||
### FR-6 — Рамка критичных запретов в deployer (BR-6, P2-1)
|
||
В `deployer.md` вынести самые критичные self-hosting-запреты в **видную рамку в начале** (сразу
|
||
после frontmatter / в начале `<context>`), как минимум: «**NEVER restart the prod `orchestrator`
|
||
(8500) container**». Существующий blockquote усилить/поднять. Инвариант анти-регресса: маркеры
|
||
`docker exec orchestrator-staging`, `pr_already_merged`, `8500`, `INFRA-WAIVED` сохраняются.
|
||
|
||
### FR-7 — Обогащение tester (BR-7, P2-3)
|
||
В `tester.md`:
|
||
- **worktree-путь:** явно указать, что тесты гоняются в worktree ветки задачи (а не в общем
|
||
`/repos/orchestrator`), чтобы исключить гонки checkout; зафиксировать корректный путь алгоритма.
|
||
- **serial_gate smoke:** в smoke `/queue` добавить проверку наличия блока `serial_gate`
|
||
(ORCH-088) в ответе.
|
||
- **покрытие ТЗ:** в `<success_criteria>` добавить, что готовность = каждый TC из
|
||
`04-test-plan.yaml` выполнен и сопоставлен с `03-acceptance-criteria.md`, а не только «файл
|
||
записан». Инвариант анти-регресса: маркеры `pytest`, `/health`, `/status`, `/queue` сохраняются.
|
||
|
||
### FR-8 — Удаление мёртвой инструкции reviewer (BR-8, P2-4)
|
||
В `reviewer.md` удалить строку-запрет «❌ Не апрувь PR от того же экземпляра Developer →
|
||
✅ выноси независимый вердикт» (защита от несуществующего кейса — reviewer всегда отдельный
|
||
agent-run). Перед удалением убедиться, что ни один тест на неё не опирается (анти-регресс reviewer
|
||
держит только `REQUEST_CHANGES` и «НЕ обновлена» — они сохраняются). Ось «независимый вердикт по
|
||
4 осям» остаётся выражена через `<task>`/`<thinking>`.
|
||
|
||
### FR-9 — Ручной rebase developer по решению ADR (BR-9, P1-2) — **зона архитектора**
|
||
Установленный факт (A-2): движок уже выполняет rebase автоматически (`auto_rebase_onto_main` в
|
||
`check_branch_mergeable`, `premerge_rebase_always=True`; serial-gate режет ветку от свежего
|
||
`origin/main`). Требование: архитектор в ADR решает — убрать/смягчить/оставить-с-пояснением шаг
|
||
`git fetch origin && git rebase origin/main` в алгоритме developer; developer.md приводится в
|
||
соответствие. БЕЗ ADR-решения промпт-строку rebase **не менять**.
|
||
|
||
### FR-10 — Язык deployer по решению ADR (BR-10, P2-2) — **зона архитектора**
|
||
Архитектор решает: унифицировать deployer на русский (как остальные 5) ЛИБО явно задокументировать
|
||
исключение («deployer — en по причине критичных команд/контрактов»). Инвариант: при любом исходе
|
||
machine-verdict ключи (`staging_status:`/`deploy_status:`/`security_status:` + значения
|
||
SUCCESS/FAILED/PASS/FAIL) и shell-команды НЕ переводятся/не ломаются. БЕЗ ADR-решения язык
|
||
**не менять**.
|
||
|
||
### FR-11 — Анти-регресс-тесты новых инвариантов (BR-11)
|
||
В `tests/test_agent_prompts_canon.py` (pure-text, без импорта `src/`, кроме TC-03 сверки реестра)
|
||
добавить проверки: плейсхолдеры даты/модели в примерах (нет литерала `created_at: 2026-`/
|
||
`model_used: claude-opus-4-8` в копируемом блоке); наличие `<escalation>` у developer/reviewer/
|
||
tester; отсутствие удалённой мёртвой строки reviewer; обогащение tester (serial_gate/worktree/
|
||
покрытие ТЗ); рамка в deployer. Существующие проверки (5 секций, 6 полей, verdict-ключи,
|
||
анти-регресс-маркеры) остаются зелёными.
|
||
|
||
## 4. Изменения API
|
||
Нет. Эндпоинты не добавляются и не меняются.
|
||
|
||
## 5. Изменения схемы БД
|
||
Нет. Схема БД не трогается.
|
||
|
||
## 6. Требования к новым/изменённым QG checks
|
||
Нет. `QG_CHECKS` / `check_*` / `STAGE_TRANSITIONS` **не трогаются**. Имена гейтов в промптах лишь
|
||
**сверяются** с существующим реестром (FR-3). `frontmatter_validation_strict` остаётся `False`
|
||
(enforcement не включается).
|
||
|
||
## 7. Совместимость / регресс
|
||
|
||
- **Машинные verdict-ключи** — байт-в-байт: `verdict:` (APPROVED|REQUEST_CHANGES), `result:`
|
||
(PASS|FAIL), `staging_status:`/`deploy_status:` (SUCCESS|FAILED), `security_status:` (PASS|FAIL).
|
||
Гарант — `test_machine_verdict_keys_preserved_exact_case`.
|
||
- **Канон 52d/52c/52e** — 5 секций в нормативном порядке (context→task→deliverables→constraints→
|
||
output_format), 6 полей схемы, правило трассировки. `<escalation>` добавляется как 6-я
|
||
необязательная секция ПОСЛЕ `</output_format>`/`</success_criteria>` — порядок обязательной
|
||
пятёрки не нарушается. Гаранты — `test_five_xml_sections_present`,
|
||
`test_six_schema_field_names_present`, `test_schema_pins_role_specific_author_and_stage`.
|
||
- **Frontmatter определения агента** — верхний `---`-блок (name/description, без `model:`)
|
||
не трогается; примеры схемы живут в теле. Гарант — `tests/test_agent_frontmatter_no_model.py`.
|
||
- **Область раската / обратимость** — docs/prompts-only; вступает в силу на следующем worktree
|
||
от `main`; прод-рестарт НЕ требуется; полностью ревертируемо одним PR.
|
||
- **Полный регресс** `pytest tests/ -q` остаётся зелёным.
|
||
|
||
## 8. Артефакты pipeline, создаваемые/обновляемые этой задачей
|
||
- Анализ (этот пакет): `01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`, `04-test-plan.yaml`.
|
||
- Архитектура: `06-adr/ADR-001-*.md` (решения P1-2 FR-9, P2-2 FR-10), при сквозном эффекте —
|
||
возможный `10-tech-risks.md`.
|
||
- Разработка: 6 промптов + `tests/test_agent_prompts_canon.py` + `CLAUDE.md`/README/`CHANGELOG.md`.
|