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

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

@@ -0,0 +1,90 @@
+# 01 — Business Requirements Document (BRD)
+
+**Work Item:** ORCH-044
+**Title:** Надёжность запуска агента: preflight ловит auth+битый флаг, --effort фикс
+**Приоритет:** Высокий (надёжность конвейера)
+**Автор запроса:** Слава, 05.06 («почему перед стартом аналитика не прошла проверка?»)
+
+## 1. Контекст и инцидент (05.06)
+Задача **ORCH-17** застряла на стадии Analysis ~30 минут. Аналитик-агент стартовал и
+мгновенно «умирал»: run-лог — **пустой файл (0 байт)**, а job в очереди оставался в
+состоянии `running` (вечное зависание без сигнала).
+
+Корневые причины (две, наложились):
+1. **`claude` Not logged in** после ребилда контейнера — токен/сессия не поднялись.
+2. **Флаг `--effort`** в связке с `--print --output-format json` (CLI 2.1.142) **гасил весь
+   stdout** — claude завершался с пустым выводом.
+
+**Главная системная проблема:** preflight-проверка пропустила обе битые задачи в работу —
+она слепа к авторизации и не ловит «битый флаг → пустой вывод».
+
+## 2. Проблема (как есть)
+- **P1. Дыра в preflight (главное).** `src/preflight.py` сознательно проверяет только
+  (a) `os.path.exists(CLAUDE_BIN)` и (b) `claude --version` (timeout 5s, без токенов).
+  Но `--version` отвечает успешно **даже когда claude НЕ залогинен** (версия — локальная
+  информация). Итог: `preflight=ok`, а реальный запуск падает `Not logged in`. Preflight
+  слеп к авторизации и пропускает заведомо нерабочие задачи в очередь.
+- **P2. `--effort` ломает вывод.** Флаг `--effort <low..max>` совместно с
+  `--print`/`--output-format json` в CLI 2.1.142 даёт **пустой stdout** — агент молча
+  умирает. Сейчас effort **отключён в проде** хотфиксом (`.env`: `ORCH_AGENT_EFFORT_*=""`),
+  но дефолты в `src/config.py` всё ещё `high`/`medium`, а документация (INFRA.md,
+  internals.md, ORCH-41) описывает effort как рабочую фичу. Несоответствие кода/доков/прода.
+- **P3. Пустой лог ≠ провал.** Агент с пустым run-логом (0 байт) и `exit 0` трактуется как
+  **успех** (`_finalize_job` → `done`, авто-advance стадии) либо вечно висит `running`.
+  Ни watchdog, ни ретрай не срабатывают. Нет сигнала об инциденте.
+
+## 3. Бизнес-последствия
+- Любой сбой авторизации или несовместимости флага → **тихое зависание** задачи без алерта.
+- Блокируется конвейер **всех** проектов (общий инстанс/очередь, self-hosting) — как было с
+  ORCH-17 (30 мин простоя, ручное вмешательство).
+- Деградация доверия к автономности оркестратора: «проверка перед стартом» не работает.
+
+## 4. Цель
+Сделать запуск агента **отказоустойчивым по входу и по выходу**:
+1. Preflight ловит отсутствие/протухание авторизации **дёшево и без траты токенов** до того,
+   как job будет заклеймлен.
+2. Разобраться с `--effort` и привести код/доки/прод к одному непротиворечивому состоянию.
+3. Пустой/невалидный результат запуска трактуется как **провал** (job → `failed`), чтобы
+   сработали watchdog/ретрай и алерт, а не вечное зависание.
+
+## 5. Заинтересованные стороны
+- **Owner/Слава** — инициатор, требует «проверки перед стартом».
+- **Все проекты на инстансе** (enduro-trails и self-hosting ORCH) — страдают от простоя.
+- **Агенты конвейера** — analyst/architect/... — все запускаются через единый launcher.
+
+## 6. Объём (Scope)
+**В объёме:**
+- Дешёвая token-free проверка авторизации в preflight.
+- Расследование и решение по `--effort` (вернуть корректно ИЛИ задокументировать как
+  unsupported и убрать из кода/дефолтов/доков).
+- Детекция «пустой лог / нет валидного result-JSON» как провала job с корректным
+  переводом в `failed` и срабатыванием ретрая/алерта.
+- Обновление документации (INFRA.md / internals.md / CHANGELOG) в том же PR.
+
+**Вне объёма:**
+- Prompt-ping (ping→pong) — **запрещено** (жжёт rate limit). Только локальные/дешёвые проверки.
+- Реформа circuit breaker / backoff-логики (используем существующие механизмы).
+- Изменение схемы стадий/конвейера.
+- Автоматический re-login claude (восстановление авторизации) — отдельная задача.
+
+## 7. Бизнес-правила
+- BR-1: Preflight **не тратит токены** и не делает сетевых вызовов к API модели.
+- BR-2: Протухшая/нечитаемая авторизация → `preflight=fail` → job **не клеймится** (остаётся
+  `queued`), пишется warning, при необходимости — алерт/брейкер.
+- BR-3: Пустой run-лог ИЛИ отсутствие валидного result-JSON при `exit 0` → job `failed`
+  (никогда не `done` и не вечный `running`).
+- BR-4: Никаких `--no-verify`/обхода хуков без явного одобрения Owner.
+- BR-5: Код, дефолты `config.py`, прод `.env` и документация по `--effort` должны быть
+  взаимно непротиворечивы после задачи.
+
+## 8. Критерии успеха (бизнес-уровень)
+- Симуляция «не залогинен» → preflight ловит до клейма, job не стартует впустую.
+- Симуляция «пустой лог + exit 0» → job становится `failed`, срабатывает ретрай/алерт.
+- Состояние `--effort` однозначно: либо работает с json-форматом, либо удалён из активного
+  пути и доков (без «мёртвого» флага в дефолтах).
+- Инцидент класса ORCH-17 больше не приводит к тихому 30-минутному зависанию.
+
+## 9. Связанные материалы
+- `src/preflight.py`, `src/queue_worker.py`, `src/agents/launcher.py`, `src/config.py`
+- `docs/history/LESSONS_ORCH-017.md`, `docs/history/LESSONS_2026-06-05.md`
+- ORCH-41 (effort/model resolver), ORCH-1 (очередь/resilience), ORCH-7 (watchdog)