orchestrator/docs/work-items/ORCH-092/01-brd.md

work_item, stage, author_agent, status, created_at, model_used

work_item	stage	author_agent	status	created_at	model_used
ORCH-092	analysis	analyst	ready-for-review	2026-06-09	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 (заполняет архитектор).