# ТЗ — ORCH-074: убрать мёртвый frontmatter `model:` + валидация имени модели

Work Item ID: ORCH-074
Базируется на: BRD `01-brd.md`. Скоп фиксирован решением Славы (08.06):
**G1 + G2 + опц. G4. G3 (routing) НЕ включаем. Эффорт НЕ трогать.**

## 1. Задействованные модули `src/` и файлы

| Файл | Изменение |
|------|-----------|
| `.openclaw/agents/analyst.md` | **G1:** удалить строку `model: claude-sonnet-4-6` из frontmatter |
| `.openclaw/agents/architect.md` | **G1:** удалить строку `model: claude-opus-4-7` |
| `.openclaw/agents/developer.md` | **G1:** удалить строку `model: claude-sonnet-4-6` |
| `.openclaw/agents/reviewer.md` | **G1:** удалить строку `model: claude-opus-4-7` |
| `.openclaw/agents/tester.md` | **G1:** удалить строку `model: claude-sonnet-4-6` |
| `.openclaw/agents/deployer.md` | **G1:** удалить строку `model: claude-sonnet-4-6` |
| `src/agents/launcher.py` | **G2:** добавить валидацию имени модели в `resolve_agent_model` (или helper), по образцу `VALID_EFFORTS`-гарда в `resolve_agent_effort` |
| `src/config.py` | **G4 (опц.):** задать `agent_fallback_model` (если архитектор решит). При G2 — возможно добавить константу/настройку валидного формата модели |
| `docs/architecture/README.md` | **AC-6:** таблица «модель/эффорт по ролям» актуализирована; нет упоминаний sonnet/opus-4-7 как «модели агента» |
| `.env.example` | **AC-3/AC-6:** добавить блок `ORCH_AGENT_MODEL_*` / `ORCH_AGENT_EFFORT_*` / `ORCH_AGENT_FALLBACK_MODEL` (сейчас в `.env.example` их НЕТ) |
| `CLAUDE.md` | **AC-6:** при необходимости — отметить, что модель агента берётся ТОЛЬКО из config (frontmatter описательный) |
| `CHANGELOG.md` | запись о доработке |
| `tests/test_resolve_agent_model.py` | **AC-2:** добавить кейсы валидации мусорного имени |

## 2. G1 — убрать мёртвый frontmatter `model:`

Удалить **только** строку `model: …` из YAML-frontmatter каждого из 6 файлов
`.openclaw/agents/*.md`. Остальные ключи (`name`, `description`, `tools`/`model`-comment)
не трогать. frontmatter остаётся валидным YAML и описательным.

Проверка (AC-1):
```
grep -L "^model:" .openclaw/agents/*.md   # должны вернуться ВСЕ 6 файлов
```
(`grep -L` печатает файлы БЕЗ совпадения — все 6 не должны содержать `^model:`.)

## 3. G2 — валидация имени модели (never-break)

Требование (НЕ предписывает архитектуру — выбор предиката за архитектором):

- Резолвенное имя модели валидируется ПЕРЕД возвратом из `resolve_agent_model`
  (либо в общем helper). Невалидное имя → `logger.warning(...)` + откат на
  следующий валидный уровень (в пределе — `agent_model_default`, а если и он
  невалиден → `""`, т.е. без флага `--model`, CLI-дефолт). **Никогда** не вернуть
  мусор, который попадёт в `--model`.
- Поведение — точная аналогия `resolve_agent_effort` (`VALID_EFFORTS`): валидный →
  как есть; невалидный → лог + дроп.
- Предикат валидности (на усмотрение архитектора, рекомендация аналитика):
  формат-чек `claude-*` (forward-compatible — новые версии моделей не требуют
  правки allowlist) ЛИБО явный `VALID_MODELS` allowlist (строже, но требует
  поддержки при выходе новых моделей). **Выбор и обоснование — в ADR.**
- **Рекомендация аналитика (форма):** оформить предикат как отдельный
  чистый helper (напр. `is_valid_model(name) -> bool` рядом с `VALID_EFFORTS`),
  а не инлайнить в `resolve_agent_model` — тогда ОДИН валидатор переиспользуется
  и резолвом модели, и чтением fallback (G4, см. §4). Финальная форма — за
  архитектором.
- Инвариант обратной совместимости: ВСЕ ныне используемые валидные имена
  (`claude-opus-4-8`, а также enduro per-project override) проходят валидацию
  без изменения поведения. Невалидным считается только мусор (опечатка,
  `gpt-4`, пустая строка после strip и т.п.).
- Контракт уровней резолва ORCH-041 сохраняется: валидация добавляется поверх,
  механизм приоритетов не меняется.

## 4. G4 — fallback_model (опционально, решает архитектор)

- `src/config.py::agent_fallback_model` сейчас `""` (флаг не прокидывается).
- Если архитектор решит включить — задать каноничное имя модели; launcher уже
  прокидывает его в `--fallback-model` (`launcher.py:374-375`, попадает в cmd
  на строке 388).
- **⚠️ Код-факт (проверено 08.06):** fallback читается НАПРЯМУЮ —
  `fb = settings.agent_fallback_model` (`launcher.py:374`) — и **НЕ проходит**
  через `resolve_agent_model`, значит валидация G2, добавленная внутри
  `resolve_agent_model`, его НЕ покроет. Следствие для архитектора: если G4
  включается, валидацию имени модели (G2) надо применить ТАКЖЕ к fallback на
  его месте чтения (или вынести валидатор в отдельный helper, который вызывают
  ОБА: и резолв модели, и чтение fallback). Иначе опечатка в `agent_fallback_model`
  обходит G2 и уезжает в `--fallback-model` — нарушение never-break.
- Если архитектор решит НЕ включать — оставить `""`, AC-5 помечается N/A в ADR.

## 5. Изменения API / схемы БД

- **API (HTTP):** нет.
- **Схема БД:** нет миграций.
- **CLI-команда агента:** формируется в `launcher._spawn` (строки 384-392).
  Меняется только КАЧЕСТВО значения `--model` (валидное/дроп), сама структура
  команды не меняется.

## 6. Требования к QG checks

- Новых QG-чеков НЕ требуется. Валидация — это runtime-гард в launcher, не
  отдельный quality-gate.

## 7. Артефакты pipeline

Должны быть созданы/обновлены в ЭТОМ PR (golden source = код + доки):
- `docs/architecture/README.md` — таблица «модель/эффорт по ролям».
- `.env.example` — блок переменных моделей/эффорта/fallback.
- `CHANGELOG.md` — запись.
- `06-adr/ADR-NNN-*.md` — решение по предикату валидации (G2) и по G4 (fallback вкл/выкл).
- ADR архитектора фиксирует: выбран вариант G1 «убрать» (не «читать frontmatter»).

## 8. Эффорт — НЕ ТРОГАТЬ

`agent_effort_*` корректны (`thinking → high`, `tester/deployer → medium`).
Менять только при явном отдельном обосновании (вне скоупа этой задачи).

## 9. Грабли

- Имена моделей — каноничные строки Claude CLI; сверить с тем, что реально
  принимает CLI на проде (`ORCH_CLAUDE_BIN`). НЕ хардкодить версию вне `config.py`.
- Если frontmatter автогенерится инструментом — убедиться, что `model:` не вернётся.
- Self-hosting: НЕ ронять прод-контейнер; деплой через «Confirm Deploy».