# 01 — BRD: ORCH-081 (ORCH-52h)

**Work Item:** ORCH-081
**Эпик:** ORCH-052 (продолжение ORCH-52a / ORCH-074)
**Тип:** Багфикс (конфигурация эффорта агентов)
**Приоритет:** HIGH
**Repo:** orchestrator (self-hosting)

## 1. Контекст и проблема

При проверке ORCH-074 (08.06) обнаружено: `resolve_agent_effort()` для **всех 6 агентов
в проде** возвращает пустую строку `''`, хотя в `src/config.py` заданы осмысленные
дефолты (`agent_effort_default="high"`, per-agent `high`/`medium`). Итог: флаг
`--effort` **не передаётся** в Claude CLI, и каждый агент бежит на встроенном
CLI-дефолте эффорта, а **не** на заявленном `high`/`medium`.

### Корень (диагностика)
В проде env-переменные `ORCH_AGENT_EFFORT_DEFAULT` и
`ORCH_AGENT_EFFORT_{ANALYST,ARCHITECT,DEVELOPER,REVIEWER,TESTER,DEPLOYER}` выставлены в
**пустую строку** (`VAR=` без значения). Pydantic Settings трактует присутствующую
env-переменную (даже пустую) как явное значение и **перебивает** дефолт класса:
`agent_effort_* = ''`. В цепочке резолва (`launcher._resolve_agent_attr`):
- per-agent `''` → falsy → пропуск (уровень 2);
- default `''` → falsy → пропуск (уровень 3);
- → возврат `''` (уровень 4, «без флага»).

Поскольку **и default тоже пуст**, привычный откат «per-agent пуст → взять default»
не спасает: откатываться не на что. Это ключевой нюанс — фикс обязан давать каждой
роли непустой «пол» (floor) даже когда И per-agent, И default env пусты.

## 2. Бизнес-ценность / зачем важно

Для Opus 4.8 (канон Anthropic) уровень reasoning-эффорта влияет на качество вывода
**сильнее**, чем у прежних моделей. Coding/agentic роли (особенно `developer`) должны
идти минимум на `high`, а `developer` — кандидат на `xhigh`. Сейчас фактически работает
неконтролируемый CLI-дефолт → прямой удар по стратегии надёжности и предсказуемости
качества всего конвейера (включая enduro-trails из общего инстанса).

## 3. Решение (бизнес-уровень)

Принят **вариант (c)** (решение Славы, 08.06): пустая строка эффорта трактуется как
«не задано» и откатывается на осмысленный per-role дефолт (а не на CLI-дефолт),
**устойчиво** к пустым env. Дополнительно — зафиксировать целевые дефолты в `config.py`
и `.env.example`.

### Целевые значения эффорта (единственный апгрейд — `developer`)
| Агент | Эффорт | Обоснование |
|-------|--------|-------------|
| analyst | high | intelligence-роль |
| architect | high | intelligence-роль |
| **developer** | **xhigh** | coding/agentic, канон Opus 4.8 → апгрейд с `high` |
| reviewer | high | intelligence-роль |
| tester | medium | механическая роль |
| deployer | medium | механическая роль |

`developer → xhigh` — единственное изменение относительно текущих config-дефолтов;
остальные значения подтверждают текущий замысел и фиксируются устойчиво.

## 4. Грабли / ограничения (из бизнес-запроса)

- **Хост-репо / env-правки НЕ переживают деплой**, если положены в git-managed файл
  (урок 08.06 про docker-compose + TZ). Источник правды для реальных значений —
  `.env` на хосте (gitignored), канон-шаблон — `.env.example`. Фикс обязан быть
  **code-side robust**: даже если прод-`.env` снова окажется с пустыми
  `ORCH_AGENT_EFFORT_*`, эффорт всё равно резолвится в целевые значения.
- **Self-hosting:** правка касается инструмента, который сейчас в проде обслуживает и
  другие проекты. Прод-контейнер `orchestrator` не ронять в рамках задачи; деплой —
  через штатный `deploy-staging` → `Confirm Deploy`.

## 5. Не-цели

- НЕ трогать model-резолв (`resolve_agent_model` — сделан в ORCH-074).
- НЕ включать G3 model-routing — все 6 агентов остаются на `claude-opus-4-8`.
- НЕ менять значения эффорта сверх согласованных (`high`/`medium`/`xhigh` для
  developer). Иные значения — отдельное взвешенное решение.

## 6. Затронутые стороны

- Все агенты конвейера (analyst → deployer) во всех проектах общего инстанса.
- Операторы (правка прод-`.env`), документация (README таблица, `.env.example`).
</content>
</invoke>