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