170 lines
17 KiB
Markdown
170 lines
17 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
|
||
---
|
||
|
||
# 01 — BRD (бизнес-требования): ORCH-092 — Промпт-аудит 6 агентов (расхардкод дат/модели, сверка гейтов, escalation, чистка мёртвых инструкций)
|
||
|
||
Work Item: **ORCH-092** · Repo: **orchestrator** · Стадия: analysis
|
||
|
||
## 1. Бизнес-контекст и проблема
|
||
|
||
ORCH-092 — **эпилог эпика ORCH-52** (канонизация системных промптов). После слоёв 52d
|
||
(XML-канон) и 52e (трассировка маркеров) системный аудит 6 промптов (`.openclaw/agents/*.md`)
|
||
выявил класс системных дефектов, способных приводить к **дрейфу и багам** в self-hosting-конвейере:
|
||
|
||
- **Хардкод даты в примерах.** Во всех 6 промптах пример frontmatter содержит жёсткое
|
||
`created_at: 2026-06-09`. Исполняющая модель — литеральный Opus 4.8: пример сильнее
|
||
инструкции «текущая дата». Риск — модель **копирует дату буквально** → все документы
|
||
всех задач получают одну и ту же дату, метаданные перестают отражать реальность.
|
||
- **Хардкод модели в примерах.** Пример несёт `model_used: claude-opus-4-8`. Если включат
|
||
model-routing (ORCH-41), промпты начнут **врать** про использованную модель — ровно та
|
||
боль, которую слой 52f чинил для README «Известные ограничения».
|
||
- **Несверённые имена гейтов.** Промпты называют имена QG-функций (`check_*`); при дрейфе
|
||
кода имя в промпте может разойтись с реальным реестром `QG_CHECKS`. *(Сверка кодом в рамках
|
||
анализа показала: текущие имена корректны — см. §6, допущение A-1; задача — закрепить сверку
|
||
как воспроизводимую проверку, а не «починить несуществующий баг».)*
|
||
- **Логические нестыковки в developer.md.** Инструкция «PR > 1500 строк → разбивай на меньшие
|
||
PR» **физически невыполнима**: конвейер = 1 задача = 1 ветка = 1 PR, разбить внутри стадии
|
||
нельзя. Инструкция `git rebase origin/main` в начале алгоритма **дублирует/конфликтует** с
|
||
автоматикой движка (serial-gate ORCH-088 режет ветку от свежего `origin/main`;
|
||
`auto_rebase_onto_main` ORCH-026 делает pre-merge rebase сам).
|
||
- **Размазанная эскалация.** Секцию `<escalation>` имеет только `architect.md`. У developer /
|
||
reviewer / tester маршруты эскалации (негодное ТЗ, FAIL, REQUEST_CHANGES) растворены в
|
||
`<constraints>` — нет единой видной точки «куда эскалировать при затыке».
|
||
- **Консистентность/качество.** `deployer.md` (самый большой, ~9.6 KB, на английском) рискует
|
||
«утопить» критичный self-hosting-запрет «НЕ рестартить 8500». `tester.md` (самый бедный,
|
||
~4.7 KB) не фиксирует worktree-путь (были гонки checkout), не проверяет serial_gate-блок и
|
||
не требует покрытия ТЗ. `reviewer.md` содержит мёртвую инструкцию про «тот же экземпляр
|
||
Developer» (в конвейере reviewer всегда отдельный agent-run).
|
||
|
||
**Это docs/prompts-only задача.** Код (`src/**`, `STAGE_TRANSITIONS`, `QG_CHECKS`, схема БД)
|
||
**не трогается**. Промпт `cat`-ается из worktree в момент запуска агента, поэтому новые
|
||
промпты вступают в силу на следующем worktree от `main` **без рестарта прод-контейнера** —
|
||
что критично для self-hosting (рестарт 8500 встаёт конвейер всех проектов).
|
||
|
||
## 2. Объём (scope)
|
||
|
||
### В объёме
|
||
- Правка 6 промптов `.openclaw/agents/{analyst,architect,developer,reviewer,tester,deployer}.md`:
|
||
расхардкод даты (P0-1) и модели (P0-2) в **копируемых примерах**; сверка имён гейтов (P0-3);
|
||
переформулировка «PR>1500» в эскалацию (P1-1); добавление `<escalation>` в developer/reviewer/
|
||
tester (P1-3); рамка критичных запретов в deployer (P2-1); обогащение tester (P2-3); удаление
|
||
мёртвой инструкции reviewer (P2-4).
|
||
- **Решения, требующие архитектора** (формализованы как открытые в §6, решаются в `06-adr/`):
|
||
P1-2 (нужен ли ручной rebase у developer при наличной автоматике), P2-2 (язык deployer:
|
||
унификация en→ru ИЛИ явно зафиксированное исключение).
|
||
- Обновление обзорной документации: `CLAUDE.md`, `docs/architecture/README.md` (при
|
||
необходимости), `CHANGELOG.md`, ADR work item, и **новые/обновлённые структурные тесты**
|
||
`tests/test_agent_prompts_canon.py` (анти-регресс новых инвариантов).
|
||
|
||
### Вне объёма
|
||
- ❌ Любая правка `src/**`, `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, схемы БД.
|
||
- ❌ Изменение машинных verdict-ключей (`verdict:` / `result:` / `staging_status:` /
|
||
`deploy_status:` / `security_status:`) — байт-в-байт неприкосновенны.
|
||
- ❌ Слом XML-канона 52d (5 обязательных секций в нормативном порядке), 52c-схемы (6 полей),
|
||
правила трассировки 52e.
|
||
- ❌ Включение enforcement frontmatter (`frontmatter_validation_strict` остаётся `False`).
|
||
- ❌ Артефакты других work item.
|
||
|
||
## 3. Заинтересованные стороны
|
||
- **Заказчик / приёмка:** Owner (Слава) — BRD-гейт ручной; решения по P1-2/P2-2.
|
||
- **Затрагиваются:** все 6 ролей конвейера (исполняют обновлённые промпты), все проекты в
|
||
общем инстансе (self-hosting), сопровождающие агенты.
|
||
- **Принимает архитектурные развилки:** архитектор (стадия architecture, `06-adr/`).
|
||
|
||
## 4. Бизнес-требования (BR)
|
||
|
||
- **BR-1 (P0-1)** — В копируемых примерах frontmatter **всех 6** промптов `created_at` —
|
||
плейсхолдер `<YYYY-MM-DD>` (НЕ конкретная дата), сопровождённый явной инструкцией: подставить
|
||
фактическую текущую дату (`date +%F`), НЕ копировать из примера буквально.
|
||
- **BR-2 (P0-2)** — В копируемых примерах **всех 6** промптов `model_used` — плейсхолдер/резолв
|
||
(`<resolve ORCH-41>`, НЕ литеральный `claude-opus-4-8`), с оговоркой подставить фактическую
|
||
модель из конфига. Факт «сейчас `claude-opus-4-8`» допускается как **справка вне копируемого
|
||
блока** (например в таблице полей), но не как литерал в примере.
|
||
- **BR-3 (P0-3)** — Все имена гейтов/QG-функций, упомянутые в промптах, **сверены** с реальным
|
||
реестром `QG_CHECKS` (`src/qg/checks.py`). Реальные несовпадения (если бы нашлись) исправлены;
|
||
**ложные подозрения не трогаются** (`check_tests_passed` верен). Сверка закреплена
|
||
воспроизводимым тестом.
|
||
- **BR-4 (P1-1)** — Инструкция developer «PR > 1500 строк → разбивай на меньшие PR» заменена на
|
||
**эскалацию**: PR слишком большой → флагировать/эскалировать (задача слишком крупная, нужна
|
||
декомпозиция **на уровне задач**, не PR).
|
||
- **BR-5 (P1-3)** — developer / reviewer / tester получают явную секцию `<escalation>` с чёткими
|
||
маршрутами: developer → `back-to:analysis` при негодном ТЗ; tester → `back-to:dev` при FAIL;
|
||
reviewer → `REQUEST_CHANGES`. (Существующая `<escalation>` у architect — эталон формата.)
|
||
- **BR-6 (P2-1)** — Критичные self-hosting-запреты deployer (прежде всего «НЕ рестартить
|
||
прод 8500») вынесены в **видную рамку в начале** промпта, чтобы не утонуть в объёме.
|
||
- **BR-7 (P2-3)** — tester обогащён: явный worktree-путь (ветка vs `/repos` — устранить гонки
|
||
checkout); smoke добавляет проверку блока `serial_gate` в `/queue` (ORCH-088); `success_criteria`
|
||
упоминает **покрытие ТЗ** (каждый TC из `04-test-plan.yaml`), не только «файл записан».
|
||
- **BR-8 (P2-4)** — Мёртвая инструкция reviewer «не апрувь PR от того же экземпляра Developer»
|
||
удалена (защита от несуществующего кейса — reviewer всегда отдельный agent-run), при сохранении
|
||
всех живых инвариантов оси документации.
|
||
- **BR-9 (P1-2, решение архитектора)** — Зафиксировать в ADR: должен ли developer выполнять
|
||
ручной `git rebase origin/main`, или это полностью делает движок (serial-gate + auto_rebase).
|
||
Промпт приводится в соответствие с принятым решением (убрать/смягчить/оставить с пояснением).
|
||
- **BR-10 (P2-2, решение архитектора)** — Зафиксировать в ADR язык deployer: унифицировать
|
||
(en→ru) ЛИБО явно задокументировать исключение («deployer — en, т.к. критичные команды/
|
||
контракты на en»). При любом исходе machine-verdict ключи и shell-команды **не ломаются**.
|
||
- **BR-11 (документация)** — Обновлены `CLAUDE.md` / `README` / ADR / `CHANGELOG.md`
|
||
(golden source = код); добавлены/обновлены структурные тесты анти-регресса новых инвариантов.
|
||
|
||
## 5. Нефункциональные требования (NFR)
|
||
|
||
- **NFR-1 (анти-регресс, критично)** — verdict-ключи `verdict:` / `result:` / `staging_status:` /
|
||
`deploy_status:` / `security_status:` сохраняются **байт-в-байт** (имя/регистр/значения);
|
||
XML-канон 52d (5 секций, нормативный порядок), 52c-схема (6 полей), правило трассировки 52e —
|
||
сохранены. `tests/test_agent_prompts_canon.py` и `tests/test_agent_frontmatter_no_model.py` —
|
||
**зелёные**.
|
||
- **NFR-2 (self-hosting безопасность)** — Изменение docs/prompts-only: `src/**` не тронут,
|
||
прод-контейнер 8500 **не перезапускается**. Новые промпты применяются на следующем worktree
|
||
от `main` без прод-рестарта.
|
||
- **NFR-3 (обратимость)** — Все правки текстовые и ревертируемы одним PR; нет миграций, нет
|
||
изменения схемы/состояния.
|
||
- **NFR-4 (консистентность канона)** — Все правки соблюдают канон Anthropic (запреты «❌ X →
|
||
✅ Y», секции в нормативном порядке); новая секция `<escalation>` размещается так, чтобы не
|
||
нарушать порядок 5 обязательных секций (после `</output_format>`, как у architect).
|
||
- **NFR-5 (отсутствие enforcement)** — `frontmatter_validation_strict` остаётся `False`;
|
||
плейсхолдеры в примерах не вызывают hard-fail валидатора (warning-only).
|
||
|
||
## 6. Допущения и ограничения
|
||
|
||
- **A-1 (сверено кодом):** реестр `QG_CHECKS` (`src/qg/checks.py`) содержит:
|
||
`check_analysis_complete`, `check_analysis_approved`, `check_architecture_done`,
|
||
`check_ci_green`, `check_review_approved`, `check_tests_passed`, `check_reviewer_verdict`,
|
||
`check_deploy_status`, `check_staging_status`, `check_branch_mergeable`, `check_security_gate`,
|
||
`check_staging_image_fresh` (+ `check_tests_local` — DEPRECATED). Имена гейтов в промптах
|
||
(`check_ci_green`, `check_reviewer_verdict`, `check_tests_passed`, `check_deploy_status`,
|
||
`check_staging_status`, `check_security_gate`) **совпадают**. Реальных несовпадений на момент
|
||
анализа НЕТ → BR-3 = «закрепить сверку», а не «исправить».
|
||
- **A-2 (сверено кодом, основание для BR-9):** `auto_rebase_onto_main` (`src/merge_gate.py`)
|
||
вызывается автоматически в `check_branch_mergeable` (`src/qg/checks.py`) при
|
||
`premerge_rebase_always=True` (дефолт), а serial-gate (ORCH-088) откладывает срез ветки на
|
||
свежий `origin/main`. Ручной rebase developer пересекается с этой автоматикой → требует решения
|
||
архитектора (не менять вслепую).
|
||
- **A-3:** Канон-тест проверяет **наличие имён полей** `created_at`/`model_used` и **литеральные
|
||
строки** `author_agent: <role>` / `stage: <stage>` в примере — плейсхолдеры даты/модели этого
|
||
не нарушают. Ни один тест не утверждает литерал `claude-opus-4-8` внутри промптов.
|
||
- **Ограничение:** P1-2 и P2-2 — зона архитектора; analyst фиксирует факты и требование-решение,
|
||
но НЕ принимает решение и НЕ правит вслепую.
|
||
|
||
## 7. Критерии успеха
|
||
|
||
Аудит-правки внесены во все 6 промптов согласно BR-1…BR-8; архитектурные развилки BR-9/BR-10
|
||
решены в ADR и отражены в промптах; документация и анти-регресс-тесты обновлены (BR-11);
|
||
анти-регресс NFR-1 соблюдён (verdict-ключи и канон не сломаны, целевые тесты зелёные).
|
||
Детальные PASS/FAIL — `03-acceptance-criteria.md`.
|
||
|
||
## 8. Риски
|
||
|
||
- Случайный слом verdict-ключа/канона при массовой текстовой правке → митигируется
|
||
структурными тестами (NFR-1).
|
||
- Плейсхолдер `<YYYY-MM-DD>` / `<resolve ORCH-41>` сам по себе мог бы быть скопирован буквально —
|
||
митигируется **явной инструкцией** «подставь фактическое, НЕ копируй».
|
||
- Принятие архитектурного решения (P1-2/P2-2) не аналитиком — митигируется явным выносом в `06-adr/`.
|
||
- Детальная карта рисков — `10-tech-risks.md` (заполняет архитектор).
|