analyst(ET): auto-commit from analyst run_id=399

docs/work-items/ORCH-081/01-brd.md

@@ -0,0 +1,82 @@
+# 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>