orchestrator/docs/work-items/ORCH-020/07-infra-requirements.md

work_item, stage, author_agent, status, created_at, model_used

work_item	stage	author_agent	status	created_at	model_used
ORCH-020	architecture	architect	proposed	2026-06-17	claude-opus-4-8

07 — Инфра-требования: ORCH-020 — Оценка задачи, запускаемая статусом «Оценка»

Work Item: ORCH-020 · Repo: orchestrator · Стадия: architecture

When-applicable. Топология контейнеров/сети не меняется; затрагиваются только Plane-конфигурация (новый статус + estimate-система), env-флаги и онбординг-канон. Это инфра-предусловия записи/триггера (NFR-7), а не изменение хост-топологии.

I-1. Топология / окружения

N/A для контейнеров/портов/сети/томов. Новых сервисов/контейнеров/портов нет. Модуль estimator работает внутри существующего процесса orchestrator (8500); никаких новых демонов/потоков.

Plane-конфигурация (предусловия, разовые, человек/онбординг):

• P-1. Статус «Оценка» на доске проекта ORCH. Создать board-статус с точным именем Оценка. Его отсутствие = fail-closed no-op (BR-T5): proj_states.get("estimate") is None → ветка инертна.
  • Группа статуса. «Оценка» — транзиентный backlog-side статус (issue в нём лишь на время оценки, затем оркестратор возвращает в Backlog). Рекомендуемая Plane-группа — backlog или unstarted (косметика индикации). Запрещена группа completed/cancelled: терминал-детект ORCH-068 (по group) иначе ложно посчитает оценку терминалом. Это обязательный инвариант группы (зеркало правила ORCH-009: терминальные группы только у Done/Cancelled/STOP).
• P-2. estimate-система Plane (для estimate_point). Настроить на проекте ORCH estimate-систему типа Points со значениями Fibonacci 1, 2, 3, 5, 8 (под project.estimate). estimate_point — FK на estimate-point этой системы; запись прогноза резолвит value → estimate_point UUID (plane_sync.get_project_estimate_points, TTL-кэш). Отсутствие/частичная конфигурация → best-effort пропуск записи estimate_point + лог, без падения конвейера (NFR-7). Поле факта point — целочисленное, устойчиво и пишется сырым int независимо от estimate-системы.

I-2. Переменные окружения / секреты

Новых секретов/токенов НЕТ (NFR-6). Запись в Plane идёт существующими PLANE_HEADERS под guard ORCH-117. Новые конфиг-флаги (config.py, env-префикс ORCH_; дефолты безопасные — пустой .env = off для не-self-hosting, self-hosting-only при пустом скоупе):

Ключ	env	Дефолт	Назначение
estimator_enabled	ORCH_ESTIMATOR_ENABLED	True	kill-switch (False → модуль инертен, нулевая регрессия)
estimator_repos	ORCH_ESTIMATOR_REPOS	""	CSV-скоуп; пусто → self-hosting only (orchestrator)
estimator_min_samples	ORCH_ESTIMATOR_MIN_SAMPLES	3	порог истории ниже которого включается bootstrap
estimator_bootstrap_tokens	ORCH_ESTIMATOR_BOOTSTRAP_TOKENS	(реализация)	дефолт токенов при пустой истории
estimator_bootstrap_cost_usd	ORCH_ESTIMATOR_BOOTSTRAP_COST_USD	(реализация)	дефолт стоимости при пустой истории
estimator_bootstrap_seconds	ORCH_ESTIMATOR_BOOTSTRAP_SECONDS	(реализация)	дефолт времени при пустой истории
estimator_sp_cost_thresholds	ORCH_ESTIMATOR_SP_COST_THRESHOLDS	0.50,2.00,5.00,12.00	пороги бакета story-points (t1,t2,t3,t5), <= по возрастанию
estimator_wall_cap_s	ORCH_ESTIMATOR_WALL_CAP_S	(реализация)	отсечка аномального wall-времени в истории (зеркало tracker_brd_review_cap_s)
estimator_max_inflight	ORCH_ESTIMATOR_MAX_INFLIGHT	(щедрый/off)	опц. семафор сглаживания массовой нагрузки (v1 неактивен)

.env.example — добавить блок ORCH_ESTIMATOR_* как канон ключей старта (норматив ORCH-101: дефолт = боевое значение).

I-3. Деплой / рестарт

• Прод-рестарт orchestrator в рамках задачи — НЕ выполнять (self-hosting инвариант: общий прод обслуживает enduro). Изменения вступают штатно: код — через прод-выкат только после staging-гейта (8501) по docs/operations/INFRA.md; флаги — через управляемый рестарт оператором по runbook.
• Plane-предусловия P-1/P-2 настраиваются в Plane UI/API оператором — вне рантайма, вне деплоя орка.
• Миграция БД — аддитивная (CREATE TABLE IF NOT EXISTS task_estimates в init_db()), применяется идемпотентно на старте; рестарт прод-контейнера ради неё не нужен (применится при следующем штатном старте). Детали — 08-data-requirements.md.
• Онбординг нового проекта (ORCH-009). Канон онбординга расширяется: статус «Оценка» становится 23-м статусом (onboard_project.py импортирует имена из plane_sync._PLANE_NAME_TO_KEY — добавление "Оценка"→"estimate" автоматически попадает в проверку; группа backlog/unstarted фиксируется в каноне групп). estimate-система Fibonacci — добавить как manual-step/ensure в онбординг-runbook (Plane CE API может не покрывать estimate-настройку → честный manual-step, fail-safe). Это follow-up по онбордингу, не блокер ORCH-020 (на существующем проекте ORCH предусловия настраиваются руками).

I-4. CI/CD

Без изменений .gitea/workflows/. Новый тест-модуль tests/test_orch020_estimator.py исполняется существующим pytest tests/ (CI / coverage-gate / merge-gate re-test) штатно — без новых шагов CI. Новых внешних зависимостей нет (эвристика — stdlib + существующие httpx/db).