orchestrator/docs/work-items/ORCH-077/02-trz.md

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-теги как разделители смысловых блоков):

• <context> — кто агент, проект orchestrator, стек, self-hosting, что прочесть перед работой (обязательный пункт «прочти CLAUDE.md и docs/architecture/README.md»).
• <task> — что делает роль на своей стадии; допускается вложенная <thinking>-подсказка (явное место для рассуждения, где уместно — FR-4).
• <deliverables> — какие файлы и куда роль создаёт через Write tool.
• <constraints> — запреты и обязательные правила (включая ролевые «Запрещено» из старых промптов).
• <output_format> — точный формат выходных документов, включая frontmatter-схему (FR-2) и machine-verdict ключи.

Дополнительные секции допустимы (напр. <success_criteria>, <escalation>), но 5 перечисленных обязательны во всех 6 промптах.

FR-2 — Инструкция эмитить обязательную frontmatter-схему 52c (BR-2)

В секции <output_format> каждого промпта явно перечислены 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)

В каждом промпте (секция <deliverables> и/или <output_format>):

• ссылка на копируемый скелет роли в docs/_templates/ (напр. analyst → 01-brd.md, 02-trz.md, 03-acceptance-criteria.md, 04-test-plan.yaml);
• ссылка на эталонный заполненный work item — ORCH-073 и/или ORCH-088 — как пример качества/полноты;
• каждый запрет в <constraints> сопровождается позитивной альтернативой: формат «❌ не делай X → ✅ делай Y» (литеральность Opus 4.8).

FR-4 — Явное место для рассуждения (CoT/thinking)

Там, где роль принимает решение (architect — выбор решения; reviewer — вынесение вердикта; tester — классификация PASS/FAIL/BLOCKED; deployer — трактовка exit-кодов/waiver), промпт содержит явную <thinking>-подсказку «сначала рассуди, потом пиши вердикт». Для механических ролей (минимально) — не обязательно.

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: <plane-id>) → 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 / ручное сравнение артефактов на эталонной задаче).