architect(ET): auto-commit from architect run_id=460
This commit is contained in:
orchestrator-deployer
@@ -57,6 +57,32 @@ created → analysis → architecture → development → review → testing →
|
||||
детально — `docs/work-items/ORCH-075/06-adr/ADR-001-pipeline-docs-standard.md`,
|
||||
`docs/work-items/ORCH-076/06-adr/ADR-001-frontmatter-contract.md`.
|
||||
|
||||
#### Слой промптов: канон Anthropic + эмиссия схемы 52c (ORCH-077, 52d — замыкает эпик 52)
|
||||
**Слой 3 (промпты).** 52b дал описательный стандарт, 52c — машинный контракт (writer + валидатор
|
||||
`REQUIRED_FIELDS`), но валидатор работал warning-only «вхолостую»: 6 системных промптов
|
||||
`.openclaw/agents/*.md` **не эмитили** поля схемы. ORCH-077 учит все 6 промптов эмитить схему и
|
||||
переписывает их в едином **каноне Anthropic** — замыкающее звено эпика. Это **docs/prompts-only**
|
||||
изменение: `src/**`, `STAGE_TRANSITIONS`, `QG_CHECKS`, состав machine-verdict ключей и схема БД —
|
||||
**не трогаются**; `frontmatter_validation_strict` остаётся `False` (эмиссия **добровольная**,
|
||||
enforcement не включается).
|
||||
- **Фиксированный XML-скелет (5 обязательных секций, нормативный порядок):** `<context>` → `<task>`
|
||||
(+ опц. `<thinking>` у решающих ролей) → `<deliverables>` → `<constraints>` (запреты в формате
|
||||
«❌ X → ✅ Y») → `<output_format>`. Доп. секции (`<success_criteria>`/`<escalation>`) — после.
|
||||
- **Аддитивная схема 52c:** `<output_format>` каждого промпта перечисляет 6 полей
|
||||
(`work_item`/`stage`/`author_agent`/`status`/`created_at`/`model_used`) с роле-специфичными
|
||||
значениями и ставит их **рядом** с machine-verdict ключом, **не меняя его имя/регистр/значения**
|
||||
(`verdict:`/`result:`/`staging_status:`/`deploy_status:`/`security_status:` — байт-в-байт). Гейты
|
||||
читают вердикты как раньше (NFR-1). Для `04-test-plan.yaml` (чистый YAML) — top-level ключи.
|
||||
- **Loading-model (важно для self-hosting):** промпт `cat`-ается из git-worktree агента в момент
|
||||
запуска (`launcher` `--system-prompt "$(cat .openclaw/agents/<role>.md)"`), НЕ запекается в образ →
|
||||
новые промпты вступают в силу на следующем worktree от `main` **без прод-рестарта**; reviewer/tester
|
||||
той же задачи исполняются уже под новыми промптами (естественный in-vivo A/B, BR-6).
|
||||
- **Анти-регресс:** структурные тесты `tests/test_agent_prompts_canon.py` (5 секций, 6 полей, точный
|
||||
регистр verdict-ключей, self-hosting-маркеры deployer'а); `test_agent_frontmatter_no_model.py`
|
||||
остаётся зелёным. **Норматив на будущее:** новые/изменённые агент-промпты следуют этому канону.
|
||||
- ADR: [adr-0021](adr/adr-0021-prompt-canon-anthropic.md); детально —
|
||||
`docs/work-items/ORCH-077/06-adr/ADR-001-anthropic-prompt-canon.md`.
|
||||
|
||||
### Модель и эффорт по ролям (ORCH-41, валидация ORCH-74)
|
||||
Модель и `--effort` каждого агента берутся из config (`src/config.py`), резолвятся `launcher.resolve_agent_model` / `resolve_agent_effort` по приоритету **project-override (`projects_json` `agent_models`/`agent_efforts`) > `ORCH_AGENT_MODEL_<AGENT>`/`ORCH_AGENT_EFFORT_<AGENT>` > `*_default` > CLI-дефолт (без флага)**. **Эффорт (ORCH-081):** ниже `*_default` добавлен непустой **per-role floor** — class-default поля `agent_effort_<role>` из `config.py` (его пустой env перебить не может). Floor — строго последний уровень (ниже default) и срабатывает ТОЛЬКО когда все уровни пусты, поэтому пустые прод-`ORCH_AGENT_EFFORT_*=` (которые pydantic трактует как явное `''` и обнуляют дефолт) больше не приводят к запуску без `--effort`: каждая роль получает свой канонический пол (developer=`xhigh`, tester/deployer=`medium`, прочие=`high`). Непустой явный конфиг по-прежнему побеждает floor; опечатка вне `VALID_EFFORTS` дропается валидацией ДО floor (never-break, не маскируется). См. `docs/work-items/ORCH-081/06-adr/ADR-001-effort-resolution-floor.md`. frontmatter `model:` в `.openclaw/agents/*.md` **удалён** (ORCH-74 G1) — он был мёртвой/лживой декларацией (launcher его не читает); config — единственный источник правды о модели. Model-routing (G3) НЕ включён — все 6 агентов на `claude-opus-4-8`.
|
||||
|
||||
|
||||
@@ -26,6 +26,7 @@ Per-work-item решения живут в `docs/work-items/<id>/06-adr/ADR-NNN-
|
||||
| adr-0018 | Авто-режим по лейблам (autoApprove + autoDeploy) | accepted | 2026-06-09 | ORCH-089 |
|
||||
| adr-0019 | Стандарт документов конвейера (PIPELINE_DOCS, слой 1) | accepted | 2026-06-09 | ORCH-075 |
|
||||
| adr-0020 | Единый frontmatter-контракт + спека handoff (reader/writer/валидатор) | accepted | 2026-06-09 | ORCH-076 |
|
||||
| adr-0021 | Канон Anthropic для агент-промптов + эмиссия frontmatter-схемы 52c | proposed | 2026-06-09 | ORCH-077 |
|
||||
|
||||
> ⚠️ Историческая коллизия: номер `0007` занят двумя файлами —
|
||||
> `adr-0007-reconciler.md` (ORCH-053) и `adr-0007-executable-self-deploy.md`
|
||||
@@ -34,6 +35,7 @@ Per-work-item решения живут в `docs/work-items/<id>/06-adr/ADR-NNN-
|
||||
> adr-0014 **amends** adr-0013 (меняет критерий merge-verify на «SHA-в-main»).
|
||||
> adr-0016 **amends** adr-0013/0014 (гарантирует открытый код-PR перед merge_pr, ORCH-082).
|
||||
> adr-0020 реализует машинный слой к adr-0019 (ORCH-52b→52c).
|
||||
> adr-0021 реализует слой промптов к adr-0019/0020 (ORCH-52d — замыкает эпик 52).
|
||||
|
||||
## Формат
|
||||
**Контекст → Решение → Альтернативы → Последствия → Связи.** Статус: proposed / accepted / superseded.
|
||||
|
||||
84
docs/architecture/adr/adr-0021-prompt-canon-anthropic.md
Normal file
84
docs/architecture/adr/adr-0021-prompt-canon-anthropic.md
Normal file
@@ -0,0 +1,84 @@
|
||||
# adr-0021: Канон Anthropic для системных промптов агентов + эмиссия frontmatter-схемы 52c
|
||||
|
||||
- **Статус:** proposed
|
||||
- **Дата:** 2026-06-09
|
||||
- **Источник:** ORCH-077 (эпик ORCH-52, слой 52d — замыкающий)
|
||||
- **Связи:** реализует слой промптов к adr-0019 (52b, PIPELINE_DOCS) и adr-0020 (52c,
|
||||
frontmatter-контракт). Детально — `docs/work-items/ORCH-077/06-adr/ADR-001-anthropic-prompt-canon.md`.
|
||||
|
||||
## Контекст
|
||||
|
||||
Эпик ORCH-52 строит сквозной контракт документации конвейера: **52b** (adr-0019) — описательный
|
||||
стандарт документов + скелеты `docs/_templates/`; **52c** (adr-0020) — машинный контракт
|
||||
`src/frontmatter.py` (reader/writer/валидатор `REQUIRED_FIELDS`) + спека `HANDOFF_PROTOCOL.md` с
|
||||
обязательной 6-польной схемой `(work_item, stage, author_agent, status, created_at, model_used)`.
|
||||
|
||||
Две незакрытые проблемы:
|
||||
1. **Цепочка 52b→52c→52d разорвана.** Writer и валидатор схемы есть, но работают warning-only
|
||||
(`frontmatter_validation_strict=False`); агенты **не эмитят** поля схемы — на входе валидатора нет
|
||||
данных, петля не замкнута.
|
||||
2. **Форма 6 промптов `.openclaw/agents/*.md` разнородна** (RU/EN, свободная структура) → снижает
|
||||
предсказуемость агентов прода, которые исполняются на КАЖДОЙ задаче ВСЕХ проектов из общего
|
||||
инстанса (self-hosting).
|
||||
|
||||
Факт загрузки (сверено `src/agents/launcher.py`): промпт `cat`-ается из git-worktree агента в момент
|
||||
запуска (`--system-prompt "$(cat .openclaw/agents/<role>.md)"`), НЕ запекается в образ.
|
||||
|
||||
## Решение
|
||||
|
||||
Ввести **обязательный канон формы** для всех агент-промптов и сделать его машинно-проверяемым.
|
||||
|
||||
1. **Фиксированный XML-скелет (5 обязательных секций, нормативный порядок):**
|
||||
`<context>` → `<task>` (+ опц. `<thinking>`) → `<deliverables>` → `<constraints>` →
|
||||
`<output_format>`. Доп. секции (`<success_criteria>`, `<escalation>`) — после. Контекст/роль
|
||||
вперёд, формат вывода последним (recency для следования схеме).
|
||||
2. **Аддитивная эмиссия схемы 52c.** `<output_format>` каждого промпта перечисляет 6 полей схемы с
|
||||
роле-специфичными значениями и инструктирует ставить их **рядом** с существующим machine-verdict
|
||||
ключом, **не меняя его имя/регистр/значения** (`verdict:`, `result:`, `staging_status:`,
|
||||
`deploy_status:`, `security_status:` — байт-в-байт). Для `04-test-plan.yaml` (чистый YAML) — как
|
||||
top-level ключи. Гейты читают вердикты как раньше (схема в boolean-вердикте не участвует).
|
||||
3. **Few-shot + позитивные альтернативы.** Ссылки на `docs/_templates/` и эталоны (ORCH-073/088);
|
||||
каждый запрет в формате «❌ X → ✅ Y».
|
||||
4. **CoT/thinking** у решающих ролей (architect/reviewer/tester/deployer).
|
||||
5. **Анти-регресс машинно.** Структурные тесты `tests/test_agent_prompts_canon.py` (без запуска
|
||||
агентов): 5 секций, 6 полей схемы, точный регистр machine-verdict ключей, ключевые
|
||||
self-hosting-маркеры (deployer: `docker exec orchestrator-staging`, `pr_already_merged`,
|
||||
«не рестартить 8500»). `test_agent_frontmatter_no_model.py` остаётся зелёным.
|
||||
6. **Enforcement не включается.** `frontmatter_validation_strict` остаётся `False` (warning-only);
|
||||
52d учит эмитить добровольно. Hard-fail — отдельная будущая задача.
|
||||
|
||||
**Границы:** docs/prompts-only. `src/**` (config, launcher, frontmatter, stages, qg/checks,
|
||||
stage_engine), `STAGE_TRANSITIONS`, `QG_CHECKS`, состав machine-verdict ключей, схема БД, `tools:`-блок
|
||||
промптов — **не трогаются**.
|
||||
|
||||
**Норматив на будущее:** любая новая правка/добавление агент-промпта следует этому канону (5 секций +
|
||||
аддитивная схема + ❌→✅). Отступление требует нового ADR.
|
||||
|
||||
## Альтернативы
|
||||
|
||||
- **Сразу включить hard-fail схемы.** Отвергнуто: правка `src/config.py` вне scope; для self-hosting
|
||||
рискованно (забытое поле валит гейт всех проектов). Сначала эмиссия, enforcement — позже.
|
||||
- **Канон как рекомендация, не норма.** Отвергнуто: теряется машинная проверяемость, эпик требует
|
||||
контракт.
|
||||
- **Запечь промпты в образ.** Отвергнуто: противоречит loading-model (cat из worktree), добавило бы
|
||||
прод-рестарт-зависимость.
|
||||
|
||||
## Последствия
|
||||
|
||||
- **+** Петля 52 замкнута: схема наполняется реальными данными на каждой стадии всех проектов.
|
||||
- **+** Единый предсказуемый канон; правки промптов вступают в силу **без прод-рестарта** (следующий
|
||||
worktree от `main`) → нулевой self-hosting-риск выкатки.
|
||||
- **+** Естественный in-vivo A/B: reviewer/tester задачи исполняются под новыми промптами в той же
|
||||
ветке (метод BR-6).
|
||||
- **−** Рост объёма промптов (митигейшн: ссылки вместо инлайна, контроль объёма).
|
||||
- **−** Риск регресса инструкции (митигейшн: построчная карта + структурные тесты + приоритетный
|
||||
review deployer/reviewer).
|
||||
- **Откат:** `git revert` PR — свободная форма возвращается, эмиссия прекращается, гейты идентичны.
|
||||
|
||||
## Связи
|
||||
- Реализует: adr-0019 (52b), adr-0020 (52c).
|
||||
- Per-work-item: `docs/work-items/ORCH-077/06-adr/ADR-001-anthropic-prompt-canon.md`.
|
||||
- Стандарты: `docs/_standards/PIPELINE_DOCS.md`, `docs/_standards/HANDOFF_PROTOCOL.md`,
|
||||
`src/frontmatter.py::REQUIRED_FIELDS`.
|
||||
- Сверено по коду: `src/agents/launcher.py`, `Dockerfile`,
|
||||
`src/config.py::frontmatter_validation_strict`, `tests/test_agent_frontmatter_no_model.py`.
|
||||
Reference in New Issue
Block a user