# 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)