docs(overview): отразить операторскую способность «Оценка» в витрине (ORCH-020)

Закрывает P1 из 12-review.md (attempt 2/3): бизнес-витрина docs/overview/
не отражала новый операторский Plane-статус «Оценка» (ORCH-020).

- business.md: бизнес-способность «Оценка задачи до запуска» + Сценарий 7.
- presentation.md: статус-жест «Оценка» на слайдах 8/9/15.
- tech-pipeline.md: новая секция «Оценка задачи: статус «Оценка»» +
  переформулировано устаревшее «управляющих статусов ровно три» в семейство
  операторских статусов-действий (запуск / гейты / STOP / Оценка).
- tech-integrations.md: то же переформулирование + запись прогноза/факта в Plane.
- tech-data-model.md: таблица task_estimates в списке вспомогательных.
- tech-observability.md: блок estimator в GET /queue + пункт «Оценка» карточки.

Также (P3): ужесточён тавтологичный assert TC-20 (был `... or True`) —
теперь проверяет, что ни один таргет ребра STAGE_TRANSITIONS не равен estimate.

Машинные факты витрины (tests/test_system_docs.py) и control-path не тронуты;
ruff на изменённом файле чист; полный pytest зелёный (2248 passed).

Refs: ORCH-020

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.env.example

@@ -282,6 +282,32 @@ ORCH_STOP_STATUS_REPOS=
 ORCH_BUG_FAST_TRACK_ENABLED=true
 ORCH_BUG_FAST_TRACK_LABEL=Bug
 ORCH_BUG_FAST_TRACK_REPOS=
+# ORCH-020: task-estimation side-mechanism, triggered by the operator Plane status
+# «Оценка» (3rd action-status, family STOP/Confirm Deploy). A leaf src/estimator.py
+# (never-raise) forecasts cost/time/tokens/story-points from the history of completed
+# tasks (deterministic, NO LLM), writes the forecast to Plane (estimate_point + comment),
+# the Telegram card and the additive task_estimates ledger, then returns the issue to
+# Backlog. On completion the fact is written to Plane `point`. OBSERVER/PRODUCER, never a
+# Quality Gate / stage. Infra precondition: create a board status «Оценка» (group
+# backlog/unstarted, NEVER completed/cancelled) + a Points estimate-system 1,2,3,5,8.
+#   ESTIMATOR_ENABLED=false   -> the «Оценка» status is not handled, nothing written
+#                                (1:1 as before ORCH-020, zero regression).
+#   ESTIMATOR_REPOS (CSV)     -> scope; EMPTY = self-hosting only (orchestrator).
+#   ESTIMATOR_MIN_SAMPLES     -> history size below which the bootstrap default blends in.
+#   ESTIMATOR_BOOTSTRAP_*     -> cold-start tokens/cost_usd/seconds when history is empty.
+#   ESTIMATOR_SP_COST_THRESHOLDS -> 4 ascending cost cut-offs (t1,t2,t3,t5) for the
+#                                story-point bucket (<=t1->1 .. <=t5->5, else 8).
+#   ESTIMATOR_WALL_CAP_S      -> cap on anomalous wall-time in history (default 24h).
+#   ESTIMATOR_MAX_INFLIGHT    -> optional bulk-smoothing semaphore (v1 generous/off).
+ORCH_ESTIMATOR_ENABLED=true
+ORCH_ESTIMATOR_REPOS=
+ORCH_ESTIMATOR_MIN_SAMPLES=3
+ORCH_ESTIMATOR_BOOTSTRAP_TOKENS=2000000
+ORCH_ESTIMATOR_BOOTSTRAP_COST_USD=3.0
+ORCH_ESTIMATOR_BOOTSTRAP_SECONDS=1800
+ORCH_ESTIMATOR_SP_COST_THRESHOLDS=0.50,2.00,5.00,12.00
+ORCH_ESTIMATOR_WALL_CAP_S=86400
+ORCH_ESTIMATOR_MAX_INFLIGHT=64
 # ORCH-094: terminal-window-aware guard for the three deploy-phase Plane status
 # setters (set_issue_awaiting_deploy / set_issue_deploying / set_issue_monitoring).
 # A DB stage=done task converges to Done idempotently instead of flapping

.task-dev.md

@@ -1,4 +1,4 @@
-Work item: ORCH-126
+Work item: ORCH-108
 Repo: orchestrator
-Branch: feature/ORCH-126-bug-queued-job-can-keep-stale-
+Branch: feature/ORCH-108-19c40858
 Stage: development

CHANGELOG.md

@@ -3,6 +3,55 @@
 Формат: [Keep a Changelog](https://keepachangelog.com/). Записи — на смысловой PR/задачу.
 
 ## [Unreleased]
+- **Оценка задачи, запускаемая Plane-статусом «Оценка»** (ORCH-020, `feat`): новый операторский
+  Plane-статус **«Оценка»** — третий член семейства action-статусов (STOP/Confirm Deploy) — запускает
+  **новый leaf `src/estimator.py`** (never-raise, kill-switch + скоуп), прогнозирующий
+  **стоимость / время / токены / сложность (story points `{1,2,3,5,8}`)** по истории завершённых задач
+  (детерминированная эвристика, **без LLM** — ADR-001 D1). Перевод issue в «Оценка» (в т.ч. **массово**
+  через Plane multi-select → N независимых вебхуков) → `handle_estimate`: прогноз (a) пишется в Plane-поле
+  `estimate_point` (через estimate-систему Fibonacci) + Plane-комментом, (b) добавляется пунктом «Оценка»
+  (время·токены·стоимость·SP) в Telegram-карточку, (c) сохраняется в **новой аддитивной таблице**
+  `task_estimates` (UPSERT по `work_item_id` → идемпотентная пере-оценка), после чего issue **возвращается
+  в Backlog** (анти-loop: Backlog не совпадает ни с одной триггер-веткой). По завершении задачи (переход в
+  `done`) **факт** (из `usage.py`) пишется в Plane-поле `point` (не затирая прогноз). Анти-disruption:
+  issue с активным job не выдёргивается (`should_estimate`). story-points — чистая функция-бакетизатор по
+  стоимости (пороги конфигурируемы). **Инвариант (NFR-1/NFR-3):** оценка — наблюдатель/продюсер, **не**
+  Quality Gate и **не** ребро стадий — `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict-ключи/схемы
+  существующих таблиц байт-в-байт не тронуты; горячий путь `resolve_agent_model`/`_spawn` не трогается.
+  Fail-closed: ключ `estimate` отсутствует в `_DEFAULT_STATES` → доска без статуса → ветка инертна
+  (зеркало STOP/Confirm Deploy). Опц. эндпоинты `POST /estimate`/`GET /estimate` (то же ядро) + read-only
+  блок `estimator` в `GET /queue`. Флаги `ORCH_ESTIMATOR_*` (`enabled` kill-switch, `repos` CSV — **пусто →
+  self-hosting only**, bootstrap-дефолты, пороги story-points). Откат = `ORCH_ESTIMATOR_ENABLED=false` →
+  модуль инертен (нулевая регрессия; enduro не затронут). Онбординг-канон расширен 23-м статусом «Оценка»
+  (группа `unstarted`, НЕ терминальная). Витрина системы `docs/overview/` обновлена под новую
+  операторскую способность «Оценка» (бизнес-способность + сценарий в `business.md`, слайды
+  `presentation.md`, статус-жест в `tech-pipeline.md`/`tech-integrations.md`, таблица
+  `task_estimates` в `tech-data-model.md`, блок `estimator`/пункт карточки в `tech-observability.md`;
+  переформулировано устаревшее «управляющих статусов ровно три» → семейство операторских
+  статусов-действий). Покрытие — `tests/test_orch020_estimator.py` (TC-01…TC-20). Детали —
+  `docs/work-items/ORCH-020/06-adr/ADR-001-task-estimation-status-trigger.md`, сквозной
+  `docs/architecture/adr/adr-0054-task-estimation-status-trigger.md`.
+- **FAQ по статусу STOP для пользователя доски** (ORCH-108, `docs`): создан пользовательский
+  FAQ `docs/operations/FAQ_STOP.md` в формате «вопрос → ответ» — что делает STOP, как отменить
+  задачу, что происходит пошагово (агент останавливается → job'ы снимаются → рабочая ветка и
+  worktree удаляются → задача → `cancelled` → Telegram+Plane; **docs-артефакты сохраняются**,
+  `main`/прод не трогаются), отложенная отмена в критичном окне (merge/deploy), явное «STOP **не
+  откатывает** влитый в `main`/прод код» (revert — отдельная задача), перезапуск только через
+  «To Analyse» с нуля, причины no-op («ничего не произошло»), где увидеть результат, и разведение
+  STOP/Approved/Confirm Deploy. **docs-only:** `src/**` / `STAGE_TRANSITIONS` / `QG_CHECKS` /
+  `check_*` / machine-verdict / схема БД — байт-в-байт не тронуты; поведение STOP — источник истины
+  ORCH-090 (`adr-0026`), FAQ его лишь документирует и ссылается, не форкая (link-first: машинные
+  детали маркеры/lease/тумбстон — только ссылками). Добавлены двусторонние перекрёстные ссылки:
+  витрина `docs/overview/business.md` (Сценарий 6) и обзор `docs/overview/tech-pipeline.md`
+  («Отмена: STOP → `cancelled`») → FAQ; FAQ → обзор + ADR ORCH-090. Структуру FAQ закрывает
+  детерминированный анти-дрейф тест `tests/test_faq_stop_doc.py` (offline, без сети/LLM/subprocess;
+  образец `tests/test_lite_setup_doc.py`): существование + 8 секций-якорей + факты-«кирпичи» +
+  кросс-ссылки + **негативный скан запрещённых утверждений на уровне предложений, а не голых
+  подстрок** (не фолзит на корректно отрицающих фразах — TR-3, проверено non-evergreen-самочеком).
+  **Норматив сопровождения:** правишь поведение STOP (`src/cancel.py` / `cancel_task` / маршрут
+  `stop`) → обнови `docs/operations/FAQ_STOP.md` в том же PR. ADR:
+  `docs/work-items/ORCH-108/06-adr/ADR-001-faq-stop-placement-and-anti-drift.md`.
+- **Source-backed `00-business-request.md` вместо хардкода `TBD`** (ORCH-119, `fix`, Bug-трек): раздел «Description» файла `00-business-request.md` теперь несёт **фактический текст запроса** из Plane-issue (`description`/`description_stripped`) вместо литерала `TBD` — терялся source-backed контекст запроса. Фикс работает на **обоих** путях создания: прямой (путь A, `serial_gate` не применим — `start_pipeline` передаёт `description` в `_create_initial_docs`) и **отложенный срез ветки** (путь B, ORCH-088, доминирует на self-hosting `orchestrator`). Для пути B `description` **персистится durable** при создании задачи (аддитивная колонка `tasks.description` через `_ensure_column`, зеркало `tasks.title`, записывается **внутри того же атомарного INSERT** `create_task_atomic` — race-safe относительно анти-dup-claim ORCH-053) и читается из строки `tasks` в `launcher._spawn` → `_materialize_deferred_branch` на момент claim (без сетевого вызова в горячем пути, NFR-4). **Fail-safe (FR-4):** пустое/whitespace/`None`/нечитаемое описание → явный безопасный маркер `_(описание отсутствует в источнике)_` через чистый рендер-хелпер `_render_business_request` (never-raise; создание задачи не падает). **Идемпотентность:** Gitea 422 (файл существует) → no-op, ранее записанное тело не перезаписывается. **Инвариант (AC-5):** `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict-ключи — байт-в-байт; единственное изменение схемы — аддитивная `tasks.description` (базовый `CREATE TABLE tasks` не тронут); анти-stale-base инвариант ORCH-088 цел (момент/условие среза не меняются — только источник данных дополняется). Обратимость — revert PR (колонка остаётся инертной). Покрытие — `tests/test_orch119_business_request.py` (TC-01 обязательный регресс red→green; TC-02…TC-07). Дополнительно в том же PR починена **тест-гермеичность** `tests/test_orch123_staging_runner_exec.py::test_r2_held_deploy_staging_not_rolled_back`: тест переиспользовал собственный (теперь смерженный в `main`) work-item id `ORCH-123`, и при дефолтном `repos_dir=/repos` staging-гейт через origin/main-fallback (`check_staging_status` → `_staging_log_from_main`) находил **реальный** `staging_status: SUCCESS`-лог ORCH-123 в `origin/main`, делая намеренно-красный гейт зелёным (флак проявлялся только в полном прогоне сьюта — singleton `repos_dir` берётся из первого импортирующего config файла, побеждая import-time `ORCH_REPOS_DIR=/tmp` этого модуля); autouse-фикстура `fresh_db` теперь пинит `repos_dir` в изолированный пустой tmp-каталог (зеркало уже пиннимого `worktrees_dir`), сохраняя проверяемость инварианта ORCH-123 R-2 (infra-held `deploy-staging` удерживается, не откатывается в `development`) независимо от порядка тестов. ADR: `docs/work-items/ORCH-119/06-adr/ADR-001-source-backed-business-request-doc.md`.
 - **Открытые вопросы аналитика → Needs Input (приоритет, неблокирование serial-gate, resume)** (ORCH-120, `fix`, трек Bug→escalate full-cycle): активирован и достроен ранее **мёртвый** путь «аналитик задаёт блокирующие вопросы → `01-questions.md` → Needs Input». Четыре согласованных изменения, аддитивно, под kill-switch, скоуп self-hosting, never-raise; `STAGE_TRANSITIONS` / реестр `QG_CHECKS` / семантика и имена `check_*` / machine-verdict-ключи / схема БД — **байт-в-байт не тронуты** (поток — pre-gate-ветка движка, **не** Quality Gate; `01-questions.md` — **сигнальный** артефакт, **не** machine-verdict). (1) **Контракт + канон.** `.openclaw/agents/analyst.md` документирует канал «блокирующие вопросы → `01-questions.md`, НЕ фабриковать deliverables» + поведение на resume; новый скелет `docs/_templates/01-questions.md`; строка манифеста + примечание о префиксе `01-` в `docs/_standards/PIPELINE_DOCS.md`. (2) **Приоритет «вопросы активны» > «файлы готовы»** в `_handle_analysis_approved_flow` (DQ-3): чистая логика решения вынесена в leaf `src/analyst_questions.py` (`questions_gate_applies`/`autopause_applies`/`questions_active`), side-effects — в `stage_engine` (`_decide_analysis_outcome`/`_emit_analysis_needs_input`/`_emit_analysis_in_review`/`_emit_analysis_empty`); блокирующие вопросы достигают Needs Input даже при сфабрикованном полном пакете. (3) **Авто-park (DQ-1)** при Needs Input через ось «пауза» ORCH-124 (`db.set_task_paused`) → задача исключается из «активного» предиката serial-gate (ORCH-088), FIFO репо не клинит, пока ждём человека; **resume + unpark** в `handle_status_start` (analysis-ветка, `db.clear_task_paused`). (4) **Гигиена устаревания (DQ-2)** — детерминированный offline freshness-supersede по `mtime` (вопросы активны, пока пакет неполон ИЛИ `01-questions.md` не старше всех 4 deliverables) → полный свежий пакет supersede’ит старый файл без зависимости от LLM (нет бесконечной петли Needs Input). Флаги (`config.py`, безопасные дефолты): `analyst_questions_gate_enabled` (kill-switch) / `analyst_questions_gate_repos` (CSV; **пусто → self-hosting only**) / `analyst_needs_input_autopause_enabled` (независимый тумблер авто-park/unpark; `False` → operator-park `POST /serial-gate/pause`). off/out-of-scope → байт-в-байт как до ORCH-120 (enduro не затронут); ORCH-066 (Needs Input только у аналитика) не расширяется. Покрытие — `tests/test_orch120_analyst_needs_input.py` (TC-01 обязательный регресс: красный до фикса, зелёный после), `tests/test_orch120_serial_gate_needs_input.py`, `tests/test_orch120_resume_unpark.py`, `tests/test_orch120_questions_artifact_canon.py` + assert в `tests/test_agent_prompts_canon.py`. Витрина системы `docs/overview/` обновлена в том же PR (ось ORCH-011): абзац пауз `tech-pipeline.md` и пункт `GET /queue` в `tech-observability.md` теперь называют **два** источника паузы (оператор + авто-park движком на Needs Input), `tech-agents.md` — when-applicable сигнальный канал `01-questions.md` у `analyst` (`tests/test_system_docs.py` зелёный). ADR: `docs/work-items/ORCH-120/06-adr/ADR-001-analyst-open-questions-needs-input.md`, сквозной `docs/architecture/adr/adr-0053-analyst-open-questions-needs-input-flow.md`.
 - **Гигиена run-ownership строки `jobs` — инвариант «queued ⇒ run_id/pid/started_at IS NULL»** (ORCH-126, `fix`, трек Bug): багфикс контрол-плейна (инцидент ORCH-124/125) — при `ORCH_SERIAL_GATE_ENABLED=false` queued analyst-job'ы зависали навсегда (job 2286: `status=queued + run_id=759/760 + pid=35/42 + started_at=NULL` — физически невозможное состояние). **Причина:** ни один путь возврата job в `queued` (restart `requeue_running_jobs` / retry `mark_job('queued')` / transient `mark_job_transient` / reap `reap_running_job('queued')`) **не сбрасывал run-ownership** (`run_id`/`pid`); после рестарта контейнера pid мог быть **переиспользован** ОС → `pid_alive(stale)=True` → job-reaper (ORCH-065) Tier-1 «видел живой» фантомный `running` и при `max_concurrency=1` клинил клейм **всей** общей очереди всех проектов. **Инвариант (adr-0052):** `status='queued' ⇒ run_id IS NULL AND pid IS NULL AND started_at IS NULL` — queued-job никогда не несёт run-ownership (история run'а — в `agent_runs`, не в `jobs.run_id`). Фикс на **существующих колонках**: `STAGE_TRANSITIONS` / реестр `QG_CHECKS` / `check_*` / machine-verdict-ключи / **схема БД** — байт-в-байт не тронуты; для здоровых job'ов и enduro поведение байт-в-байт; миграция не требуется. ADR: `docs/work-items/ORCH-126/06-adr/ADR-001-queued-job-run-ownership-hygiene.md`, сквозной `docs/architecture/adr/adr-0052-queued-job-run-ownership-invariant.md`.
   - **D1 — Forward-cleanup на всех путях возврата в `queued` (FR-1/AC-1):** `requeue_running_jobs` / `mark_job('queued')` / `mark_job_transient` / `reap_running_job('queued')` выставляют `run_id=NULL, pid=NULL` той же UPDATE-транзакцией, что чистит `started_at`/`finished_at`. Атомарные `status`-guard'ы (`reap_running_job … WHERE status='running'`, rowcount) — **сохранены байт-в-байт** (restart-safe, гонка worker↔reaper↔monitor — TR-4). Каллер-переданный `run_id` для `queued` **игнорируется** (инвариант важнее: `launcher._finalize_permanent`/reaper по-прежнему передают старый `run_id`, но для `queued` он сбрасывается). Безусловно — исправление инварианта данных, без флага (D6).

README.md

@@ -149,6 +149,12 @@ uvicorn src.main:app --reload --port 8500
 | `ORCH_BUG_FAST_TRACK_ENABLED` | Kill-switch багфикс-трека (ORCH-019): задача с меткой Plane `Bug` пропускает стадию `architecture`; `false` → старт и маршрут 1:1 как до ORCH-019 (нулевая регрессия) | `true` |
 | `ORCH_BUG_FAST_TRACK_LABEL` | Имя метки Plane, активирующей багфикс-трек (ORCH-019) | `Bug` |
 | `ORCH_BUG_FAST_TRACK_REPOS` | CSV область репо для багфикс-трека; **пусто → self-hosting only** (`orchestrator`) — enduro подключается явным CSV (ORCH-019) | `""` |
+| `ORCH_ESTIMATOR_ENABLED` | Kill-switch оценки задачи (ORCH-020): Plane-статус «Оценка» прогнозирует стоимость/время/токены/story-points по истории; `false` → статус не обрабатывается, ничего не пишется (нулевая регрессия) | `true` |
+| `ORCH_ESTIMATOR_REPOS` | CSV область репо для оценки; **пусто → self-hosting only** (`orchestrator`) — enduro не затронут (ORCH-020) | `""` |
+| `ORCH_ESTIMATOR_MIN_SAMPLES` | Порог истории, ниже которого подмешивается bootstrap-дефолт прогноза (ORCH-020) | `3` |
+| `ORCH_ESTIMATOR_BOOTSTRAP_TOKENS` / `_COST_USD` / `_SECONDS` | Bootstrap-прогноз при пустой истории (токены/стоимость/время; ORCH-020) | `2000000`/`3.0`/`1800` |
+| `ORCH_ESTIMATOR_SP_COST_THRESHOLDS` | 4 возрастающих кат-оффа стоимости (t1,t2,t3,t5) для бакета story-points (`<=t1→1`…`<=t5→5`, иначе `8`; ORCH-020) | `0.50,2.00,5.00,12.00` |
+| `ORCH_ESTIMATOR_WALL_CAP_S` / `_MAX_INFLIGHT` | Отсечка аномального wall-времени в истории / опц. семафор сглаживания массовой нагрузки (ORCH-020) | `86400`/`64` |
 | `ORCH_AGENT_HOME_DIR` | ORCH-101: HOME акторских процессов + таргет маунтов `.claude`/`.ssh` + `ARG APP_HOME` (группа ORCH-040) | `/home/slin` |
 | `ORCH_AGENT_GIT_NAME` / `ORCH_GIT_EMAIL_DOMAIN` | ORCH-101: git-идентичность коммитов агентов (`claude-bot@mva154.local` при дефолтах) | `claude-bot` / `mva154.local` |
 | `ORCH_STAGING_PORT` | ORCH-101: порт staging (читают `image_freshness` и compose); guard fail-closed при совпадении с прод-портом (ORCH-058 AC-9) | `8501` |

docs/architecture/README.md

@@ -25,6 +25,7 @@
 - **FS ownership detect** (`src/fs_normalize.py`, ORCH-057 — [adr-0031](adr/adr-0031-legacy-ownership-normalization.md)) — чистый **never-raise** leaf (паттерн `serial_gate`/`preflight`), закрывает пробел ORCH-040: при миграции на `user: "1000:1000"` legacy `root:root` файлы в `/repos` ломали создание worktree под uid 1000 (`ensure_worktree` → сырой `fatal: … Permission denied`, агент не стартовал). Три слоя: (1) **D1** — `src/git_worktree.py::ensure_worktree` классифицирует класс «нет прав» (`Permission denied`/`could not create leading directories`/`insufficient permission`/`EACCES`/`EPERM`) и поднимает actionable `RuntimeError` с причиной + лечащей командой (не-прав-ошибки сохраняют прежний контракт — меняется только формулировка, не факт сбоя); (2) **D2** — `scan_ownership(roots, target_uid=os.getuid())` обходит `/repos/_wt`, `<repo>/.git/{objects,worktrees}`, `data/runs` с ранним выходом при первом `st_uid != target_uid` + TTL-кэш; (3) **D3** — best-effort вызов на старте `main.lifespan` → WARNING + Telegram при mismatch (claim **НЕ** блокируется — внятный ранний отказ даёт D1 в точке launch, знающей repo; preflight-блок отвергнут как repo-слепой → регресс enduro). Опц. `normalize()` chown'ит только при `CAP_CHOWN` (под uid 1000 — no-op; init-контейнер/root-entrypoint отвергнуты — реинтродукция root-контекста + self-deploy compose). Фактическая нормализация = **операторская процедура** под root на хосте (`INFRA.md` «Миграция uid»). Условность `applies(repo)` first: `fs_normalize_enabled` (kill-switch) + `fs_normalize_repos` (CSV, пусто → self-hosting only). Наблюдаемость — блок `fs_ownership` в `GET /queue`; опц. `POST /fs-normalize/check`. `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict/схема БД — не тронуты. Детали — `docs/work-items/ORCH-057/06-adr/ADR-001-legacy-ownership-normalization.md`.
 - **Metrics endpoint** (`src/metrics.py` + `GET /metrics`, ORCH-099 — [adr-0030](adr/adr-0030-metrics-endpoint.md)) — лёгкий **read-only** leaf-сборщик (`build_metrics() -> dict`, never-raise по разделам, паттерн `serial_gate.snapshot()`) + тонкий эндпоинт (стиль `GET /queue`). Отдаёт JSON-«сырьё» о самом орке (стадии задач / очередь jobs / agent-liveness / стоимость-токены) как **стабильный машинный контракт для sidecar F1b** (`watchdog/`, отдельная задача — наблюдатель отделён от наблюдаемого). Только чтение существующих `tasks`/`jobs`/`agent_runs` + in-memory-снапшотов (`worker.breaker`); два read-only helper'а в `db.py` (`get_running_agents`/`agent_cost_totals`). Логику мониторинга (пороги/алерты/история/Telegram) НЕ несёт — это F1b. Контракт ниже (§ «Сырьё-эндпоинт `/metrics`»). Kill-switch `metrics_endpoint_enabled` (дефолт `True`). `STAGE_TRANSITIONS`/`QG_CHECKS`/схема БД — не тронуты.
 - **Lessons journal** (`src/lessons.py` + таблица `lessons`, ORCH-098 — реализовано, [adr-0034](adr/adr-0034-lessons-journal.md)) — машинный журнал уроков (структурированная база отклонений конвейера); шаг 1 эпика саморазвития (домен 0 «Фундамент», F2; топливо петли самообучения 8A), фундамент для будущих ретроспективщика (E2)/приоритизатора RICE (E3)/Стрим. Чистый **observer-leaf** (never-raise, паттерн `serial_gate`/`coverage_gate`/`metrics`): `record()`/`get()`/`update()`/`snapshot()`. **Аддитивная идемпотентная таблица `lessons`** (`CREATE TABLE IF NOT EXISTS` в `init_db()`, restart-safe) с полями контекста (`work_item_id`/`task_id`/`stage`/`agent`/`repo`), анализа (`root_cause`/`suggestion`), статуса (`status`/`related_task`) и **атрибуции — сразу и нуллабельно** (`attribution`/`target_repo`/`target_domain`, требование Славы 10.06 / NFR-6, заполняется позже ретроспективщиком/человеком) + `source`/`detail`; без `enum`-констрейнтов (слаги forward-compatible). **Автозапись 4 типов** (`source="auto"`, best-effort, дедуп в окне; `transient_retry` — только на исчерпании бюджета ретраев) тонкими врезками: `gate_failure` (`stage_engine._handle_qg_failure_rollbacks`), `merge_hold` (`merge_gate._handle_merge_verify` HOLD), `transient_retry` (merge-retry/launcher transient budget-exhaustion), `deploy_degraded` (post-deploy `DEGRADED → set_repo_freeze`, урок слоя-3 «деплой OK / прод сломан», ET-8). Эндпоинты `GET /lessons` (read-only, фильтры), `POST /lessons` (ручная запись), `POST /lessons/{id}` (update/доклассификация), + read-only ключ `lessons` в `GET /queue`. **Расхождение с гейт-шаблоном:** журнал observer-only → **НЕ скоупится по репо** (kill-switch `lessons_enabled` only, без `lessons_repos`); репо-разрез — на выборке (`repo`-колонка/фильтр), enduro не затронут (общая БД, аддитивная таблица). `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict/схемы существующих таблиц — байт-в-байт не тронуты (журнал не участвует в решении гейта). Kill-switch `lessons_enabled` (env `ORCH_LESSONS_ENABLED`, дефолт `True`). Детали — `docs/work-items/ORCH-098/06-adr/ADR-001-lessons-journal.md`.
+- **Task estimator** (`src/estimator.py` + таблица `task_estimates`, ORCH-020 — [adr-0054](adr/adr-0054-task-estimation-status-trigger.md)) — чистый **never-raise** leaf (паттерн `bug_fast_track`/`coverage_gate`/`lessons`), прогнозирующий **стоимость/время/токены/сложность (story points `{1,2,3,5,8}`)** задачи по запросу оператора. Триггер — **новый операторский Plane-статус «Оценка»** (третий член семейства action-статусов STOP/Confirm Deploy: fail-closed `proj_states.get("estimate")`-ветка в `handle_issue_updated`, ключ `estimate` намеренно отсутствует в `_DEFAULT_STATES`). Механизм прогноза — **детерминированная эвристика по истории** (средние токены/время/стоимость похожих `done`-задач того же `repo`+`track` через read-only `usage.py`-агрегаты; bootstrap при пустой истории; story-points — чистая функция-бакетизатор по `forecast_cost_usd` с конфигурируемыми порогами) — **без LLM-вызова** (NFR-4/NFR-5 + политика ORCH-118). Прогноз пишется в Plane-поле `estimate_point` (+ коммент), пункт «Оценка» в Telegram-карточке и аддитивную таблицу `task_estimates` (UPSERT по `work_item_id`, леджер прогноз↔факт — фундамент калибровки ORCH-8); затем issue возвращается в `Backlog` (анти-loop: `backlog` не триггер-ветка). По завершении задачи факт (из `usage.py`) пишется в поле `point`. Анти-disruption: issue с активным job → no-op (не выдёргивать in-flight). Все записи в Plane — под guard ORCH-117; отсутствие estimate-системы → best-effort пропуск. **Инвариант:** оценка — наблюдатель/продюсер, не Quality Gate и не переход стадии; `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict/схемы существующих таблиц + горячий путь `resolve_agent_model`/`resolve_agent_effort`/`_spawn` — **байт-в-байт не тронуты**. Kill-switch `estimator_enabled` + скоуп `estimator_repos` (пусто → self-hosting only); read-only блок `estimator` в `GET /queue`. Подробнее ниже (§ «Оценка задачи (ORCH-020)»). Детали — `docs/work-items/ORCH-020/06-adr/ADR-001-task-estimation-status-trigger.md`.
 - **Sidecar-watchdog F1b** (`watchdog/` + сервис `orchestrator-watchdog`, ORCH-100 — [adr-0033](adr/adr-0033-sidecar-watchdog.md)) — **мозг мониторинга в ОТДЕЛЬНОМ контейнере** (наблюдатель отделён от наблюдаемого, C-1): код в репо орка (`watchdog/`), рантайм — свой образ (`watchdog/Dockerfile`, `python:3.12-slim`, **stdlib-only**) + сервис в `docker-compose.yml` (`network_mode: host`, read-only `docker.sock`, `mem_limit: 128m`). На каждом тике собирает 4 источника: `GET /metrics` орка (F1a/ORCH-099), хост (диск/inode/память/CPU, stdlib), статусы контейнеров через read-only `docker.sock` (GET-only, без `docker` SDK), пинг Plane/Gitea/Anthropic. Каждый сигнал → **обобщённая чистая** `decide(signal_active, prev, now, cooldown)` (генерализация `disk_watchdog.decide_action`, per-signal in-memory `AlertState`) → алерт в **собственный** Telegram-канал sidecar (`WATCHDOG_TG_*`, **НЕ** импорт `src/notifications.py`). Особый сигнал `orch_down` — `/metrics` не отвечает (наблюдатель жив, наблюдаемый лёг). Диск: штатные 85% остаются за `disk_watchdog` (ORCH-063, нулевой дубль), sidecar — `orch_down` + opt-in потолок 97% (default off). never-raise, kill-switch `WATCHDOG_ENABLED`, строго read-only к наблюдаемому; `src/**`/`STAGE_TRANSITIONS`/`QG_CHECKS`/схема БД орка — не тронуты. Подробнее ниже (§ «Sidecar-watchdog F1b»). Детали — `docs/work-items/ORCH-100/06-adr/ADR-001-sidecar-watchdog.md`.
 
 ## Сырьё-эндпоинт `/metrics` для sidecar (ORCH-099 — design)
@@ -288,6 +289,56 @@ reviewer-ось обзорных доков (ORCH-079) расширена на
 вводится, рантайм байт-в-байт. Подробнее: [adr-0039](adr/adr-0039-system-overview-docs-canon.md),
 детально — `docs/work-items/ORCH-011/06-adr/ADR-001-system-overview-canon.md`.
 
+## Оценка задачи (ORCH-020 — реализовано)
+
+Операторская способность прогнозировать **стоимость / время / токены / сложность (story points
+`{1,2,3,5,8}`)** задачи **до отправки её в работу**, чтобы планировать бэклог. Запуск — **операторский
+жест в Plane**: перевод issue в выделенный статус **«Оценка»** (массово через multi-select). Реализуется
+leaf-модулем `src/estimator.py` + точечными врезками; **вне конвейера QG** (наблюдатель/продюсер, не
+гейт). `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict-ключи / схемы существующих таблиц /
+горячий путь запуска агентов — **байт-в-байт не тронуты** (NFR-1/NFR-3).
+
+- **Триггер — третий член семейства action-статусов** (STOP/ORCH-090, Confirm Deploy/ORCH-059):
+  `plane_sync._PLANE_NAME_TO_KEY["Оценка"]="estimate"`, ключ **намеренно отсутствует** в `_DEFAULT_STATES`
+  (fail-closed); в `handle_issue_updated` — ветка `estimate_state = proj_states.get("estimate")` →
+  `handle_estimate` (off-loop `asyncio.to_thread`, never-raise). Доска без статуса → ветка инертна
+  (нулевая регрессия, enduro не затронут). Массовость даёт сам Plane (N issue → N вебхуков), спец-batch-кода
+  нет.
+- **Механизм прогноза — детерминированная эвристика по истории (БЕЗ LLM).** Прогноз = средние
+  токены/время/стоимость похожих **завершённых** задач (`repo` + `track` ORCH-019) через read-only
+  агрегаты `usage.py`; пустая история → bootstrap-дефолты; story-points — чистая функция-бакетизатор по
+  `forecast_cost_usd` с конфигурируемыми порогами. **Отказ от LLM-оценщика — ключевое решение** (NFR-4:
+  стоимость оценки; NFR-5: massive multi-select не должен конкурировать за единственный LLM-транспорт с
+  боевыми агентами; политика determinization ORCH-118). Контракт `estimate(...)` — граница расширения под
+  будущий гибрид (не строится сейчас; Шаг 2 / выбор модели — вне объёма, follow-up с зависимостью ORCH-13).
+- **Анти-disruption + авто-возврат + анти-loop:** `applies(repo)` ПЕРВЫМ (локально) + `has_active_job_for_task`
+  (активный job → no-op, in-flight не выдёргивается); после оценки `set_issue_backlog`; `backlog` не
+  совпадает ни с одной триггер-веткой → возврат = no-op-эхо.
+- **Запись в Plane:** прогноз story-points → `set_issue_estimate_point` (FK на estimate-point estimate-
+  системы, резолв `value→uuid` через `get_project_estimate_points`); факт (на `done`) → `set_issue_point`
+  (устойчивый int); коммент → `add_comment`. Все под `_guard_allows_write` (ORCH-117); отсутствие
+  estimate-системы → best-effort пропуск + лог (NFR-7).
+- **Персистентность:** аддитивная таблица `task_estimates` (`UNIQUE(work_item_id)` → идемпотентная
+  пере-оценка UPSERT; `task_id` нуллабелен — issue на бэклоге). Леджер прогноз↔факт — фундамент петли
+  калибровки (ORCH-8).
+- **Поверхности:** пункт «Оценка» (время·токены·стоимость) в общей Telegram-карточке (`notifications`,
+  never-raise, ORCH-087/095-совместимо) + Plane-коммент.
+- **Факт на `done`:** best-effort врезка в `stage_engine.advance_stage` (блок `next_stage=="done"`, после
+  terminal-sync): факт из `usage.py` → бакет → `set_actual` + `set_issue_point`; `estimate_point` не
+  перезаписывается.
+- **Флаги/наблюдаемость:** `estimator_enabled` (kill-switch) + `estimator_repos` (CSV; **пусто →
+  self-hosting only**) + тюнинг (`estimator_min_samples`/bootstrap-дефолты/`estimator_sp_cost_thresholds`/
+  `estimator_wall_cap_s`/`estimator_max_inflight`); read-only блок `estimator` в `GET /queue`; опц.
+  `POST /estimate?work_item=<id>` (то же ядро: UPSERT + estimate_point + коммент + карточка + возврат в
+  Backlog) и `GET /estimate?work_item=<id>` (прогноз vs факт) — удобство/диагностика, не основной триггер
+  (массовый путь — Plane multi-select; `POST /estimate/backlog` в этот срез не вошёл).
+- **Инфра-предусловия (NFR-7):** статус «Оценка» (группа `backlog`/`unstarted`, **не** терминальная) +
+  estimate-система Plane типа Points с Fibonacci `1/2/3/5/8`; онбординг ORCH-009 расширяется на 23-й статус.
+
+Подробнее: [adr-0054](adr/adr-0054-task-estimation-status-trigger.md), детально —
+`docs/work-items/ORCH-020/06-adr/ADR-001-task-estimation-status-trigger.md`,
+`docs/work-items/ORCH-020/07-infra-requirements.md`, `08-data-requirements.md`.
+
 ## Конвейер и Quality Gates
 
 ```
@@ -1473,6 +1524,7 @@ Monitoring after Deploy → Done
 - `job_deps` — декларативные зависимости задач (ORCH-026, Уровень B): `(task_id, depends_on_task_id)`, аддитивная; источник истины планировщика для гейта «B ждёт A»
 - `repo_freeze` — durable per-repo rollback-freeze (ORCH-088, FR-5): `(id, repo, frozen_at, reason, work_item_id, cleared_at)`, аддитивная append-only; активный freeze ⇔ строка репо с `cleared_at IS NULL`. Выставляется post-deploy `DEGRADED` (`set_repo_freeze`), снимается вручную (`POST /serial-gate/unfreeze` → `cleared_at=now`). Гейтит serial-claim безусловно (деградировавшая задача уже `done`)
 - `lessons` — машинный журнал отклонений конвейера (ORCH-098, FR-1): `(id, created_at, updated_at, lesson_type, work_item_id, task_id, stage, agent, repo, root_cause, suggestion, status, related_task, attribution, target_repo, target_domain, source, detail)`, аддитивная идемпотентная (`CREATE TABLE IF NOT EXISTS` + три индекса); колонки атрибуции (`attribution`/`target_repo`/`target_domain`) — нуллабельны и присутствуют сразу (NFR-6), без `enum`-констрейнтов (слаги forward-compatible). Автозапись 4 типов (`gate_failure`/`merge_hold`/`transient_retry`/`deploy_degraded`, `source="auto"`, дедуп в окне `lessons_dedup_window_s`) + ручная (`source="manual"`); observer-only (не участвует в решении гейта). Leaf `src/lessons.py` never-raise, kill-switch `lessons_enabled` (без `*_repos` — журнал не скоупится по репо, репо-разрез на выборке)
+- `task_estimates` — леджер прогноз↔факт оценки задачи (ORCH-020, FR-T9): `(id, work_item_id UNIQUE, task_id, repo, forecast_tokens/seconds/cost_usd/story_points, actual_tokens/seconds/cost_usd/story_points, source, estimate_count, created_at, updated_at)`, аддитивная идемпотентная (`CREATE TABLE/INDEX IF NOT EXISTS`, паттерн `coverage_baseline`/`lessons`). Ключ — `work_item_id` (issue может не иметь `task` на момент оценки — бэклог; `task_id` нуллабелен, заполняется при старте); `UNIQUE(work_item_id)` → идемпотентная пере-оценка UPSERT (`estimate_count` инкрементится). Дельта прогноз↔факт вычисляется на чтение (не хранится). Пишет **только** self-hosting-скоуп (`estimator_repos` пуст → orchestrator; enduro не затронут). Leaf `src/estimator.py` never-raise; observer/producer — схемы существующих таблиц не тронуты
 - `transition_lease` — durable-владение side-effectful переходом стадии (ORCH-114, FR-1): `(task_id PK, owner, owner_pid, owner_boot_id, run_id, stage, acquired_at)`, аддитивная идемпотентная (`CREATE TABLE IF NOT EXISTS`, паттерн `repo_freeze`/`coverage_baseline`). Активная строка ⇔ актор держит владение переходом задачи; **живой** владелец ⇔ `owner_boot_id == <boot-id процесса>` И `pid_alive(owner_pid)` (рестарт ⇒ новый boot-id ⇒ прежние lease мертвы → реклейм). Захват — атомарный rowcount-guard (паттерн `claim_next_job`/`reap_running_job`); release в `try/finally`; потолок возраста = Tier-3 `reaper_max_running_s` (без собственного TTL — NFR-6). Парная CAS-запись стадии — `update_task_stage_cas(task_id, expected_stage, new_stage)` (`UPDATE … WHERE id=? AND stage=?`). Leaf `src/transition_lease.py` never-raise, kill-switch `transition_lease_enabled` + `transition_lease_repos` (пусто → self-hosting only). Обобщает in-memory `finalizer_liveness` (ORCH-113) до durable cross-path; схемы существующих таблиц не тронуты
 
 ## Изоляция (git worktree, ORCH-2)
@@ -1483,7 +1535,7 @@ Monitoring after Deploy → Done
 |--------|------|----------|
 | GET | `/health` | health check |
 | GET | `/status` | активные задачи (stage != done) |
-| GET | `/queue` | очередь: counts + max_concurrency + resilience + reconcile (ORCH-053) + reaper (ORCH-065) + post_deploy (ORCH-021) + task_deps (ORCH-026) + serial_gate (ORCH-088) + auto_labels (ORCH-089) + stop (ORCH-090) + lessons (ORCH-098) + transition_lease (ORCH-114) + последние jobs |
+| GET | `/queue` | очередь: counts + max_concurrency + resilience + reconcile (ORCH-053) + reaper (ORCH-065) + post_deploy (ORCH-021) + task_deps (ORCH-026) + serial_gate (ORCH-088) + auto_labels (ORCH-089) + stop (ORCH-090) + estimator (ORCH-020) + lessons (ORCH-098) + transition_lease (ORCH-114) + последние jobs |
 | GET | `/metrics` | ORCH-099 (FND/F1a): read-only машинное «сырьё» для sidecar F1b — конверт `schema_version`/`generated_at`/`clk_tck` + разделы `stages`/`queue`/`agents` (liveness: pid/runtime/cpu_ticks)/`cost`. never-raise по разделам; kill-switch `ORCH_METRICS_ENABLED` (дефолт `True`). Контракт — см. раздел «Сырьё-эндпоинт `/metrics`» |
 | POST | `/serial-gate/unfreeze` | ORCH-088 (FR-5): ручное снятие per-repo rollback-freeze (query/body `repo=<repo>`) → `{ok, repo, cleared, frozen}`; идемпотентно. Альтернатива — `UPDATE repo_freeze SET cleared_at=datetime('now') WHERE repo=? AND cleared_at IS NULL` |
 | POST | `/serial-gate/pause` | ORCH-124 (D7): поставить задачу на паузу для serial-gate (query/body `work_item=<id>`) → `{ok, work_item, task_id, paused_at}`; идемпотентно. Паузнутый предшественник не держит FIFO против срочного успешника (пауза ≠ cancel, ≠ глобальный kill-switch); НЕ обходит `repo_freeze`/`task_deps` |
@@ -1492,6 +1544,8 @@ Monitoring after Deploy → Done
 | GET | `/lessons` | ORCH-098 (FR-4): read-only выборка журнала уроков; query-фильтры `type`/`status`/`repo`/`work_item`/`limit` → `{enabled, lessons:[…]}` (всегда `200`, чтение не мутирует). При `lessons_enabled=False` → `{enabled:false, lessons:[]}` |
 | POST | `/lessons` | ORCH-098 (FR-5): ручная запись урока (JSON-тело, `lesson_type` обязателен, `source="manual"` не дедупится) → `{id}`; при выключенном флаге → `{enabled:false}` |
 | POST | `/lessons/{id}` | ORCH-098 (FR-5): доклассификация/обновление урока (`status`/`attribution`/`target_*`/`related_task`/`root_cause`/`suggestion`), стампит `updated_at` → `{ok}` |
+| POST | `/estimate` | ORCH-020 (**опц.**): произвести/обновить прогноз одной задачи (query `work_item=<id>`) — то же ядро, что статус-триггер «Оценка» (UPSERT в `task_estimates` + `estimate_point` + коммент + карточка + возврат в Backlog), идемпотентно → `{ok, work_item, forecast}`; при выключенном/вне-скоупе флаге → `{enabled:false}`. Не основной путь (основной — статус «Оценка») |
+| GET | `/estimate` | ORCH-020 (**опц.**): прочитать прогноз vs факт из `task_estimates` (query `work_item=<id>`) → `{ok, work_item, estimate}` (или `estimate:null`) |
 | POST | `/webhook/plane` | Plane webhook |
 | POST | `/webhook/gitea` | Gitea webhook (push, PR, CI status) |
 

docs/architecture/adr/adr-0054-task-estimation-status-trigger.md

@@ -0,0 +1,94 @@
+---
+work_item: ORCH-020
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-17
+model_used: claude-opus-4-8
+---
+
+# ADR-0054: Оценка задачи — операторский статус-триггер «Оценка» + детерминированная эвристика по истории
+
+Сквозной (cross-cutting) ADR. Детальное решение задачи —
+`docs/work-items/ORCH-020/06-adr/ADR-001-task-estimation-status-trigger.md`.
+
+Статус: **Proposed** · Дата: 2026-06-17 · Источник: **ORCH-020**
+
+## Контекст
+
+Заказчик планирует бэклог вручную и хочет видеть прогноз **стоимости / времени / токенов / сложности
+(story points `{1,2,3,5,8}`)** до отправки задачи в работу. Ключевое требование триггера (после REJECT
+2026-06-17): оценка — **операторский жест в Plane** (перевод issue в выделенный статус «Оценка»,
+**массово** через multi-select), а не невидимый авто-шаг на `start_pipeline`. Шаг 2 (адаптивный выбор
+модели) — **вне объёма**.
+
+Решение пересекает несколько подсистем (webhook-роутинг, `plane_sync`, БД, `notifications`, `stage_engine`
+done-хук), поэтому фиксируется сквозным ADR. Опирается на установленные инварианты платформы:
+- **Семейство операторских action-статусов** STOP (ORCH-090) / Confirm Deploy (ORCH-059): fail-closed
+  `.get("<key>")`-ветка в `handle_issue_updated`, ключ **намеренно отсутствует** в `_DEFAULT_STATES`.
+- **Write-guard ORCH-117** — все записи в Plane изолированы от тест/worktree-процессов.
+- **leaf-паттерн** (serial_gate/coverage_gate/bug_fast_track/lessons): never-raise, kill-switch, скоуп
+  `*_repos` (пусто → self-hosting only), read-only блок в `GET /queue`.
+- **determinization-политика ORCH-118** (`llm-usage-policy.md`): не вводить avoidable LLM-пути.
+
+## Решение
+
+**Вводим третий член семейства action-статусов — «Оценка» — как side-механизм, делегирующий новому leaf
+`src/estimator.py`.** Механизм прогноза — **детерминированная эвристика по истории** (чистые функции, без
+LLM-вызова). Аддитивно, под kill-switch, скоуп self-hosting, never-raise, fail-safe:
+
+1. **Триггер (D4).** `_PLANE_NAME_TO_KEY["Оценка"]="estimate"` (НЕ в `_DEFAULT_STATES`); fail-closed ветка
+   `proj_states.get("estimate")` → `handle_estimate` (off-loop `to_thread`, зеркало `handle_stop`).
+   Взаимоисключение жестов — по различию UUID статусов, не по порядку.
+2. **Анти-disruption + авто-возврат + анти-loop (D5).** Guard `applies(repo)` ПЕРВЫМ (локально) +
+   `has_active_job_for_task` (активный job → no-op, не выдёргивать in-flight). После оценки —
+   `set_issue_backlog`; `backlog` не совпадает ни с одной триггер-веткой → возврат = no-op-эхо.
+3. **Механизм прогноза (D1/D2/D3).** **Без LLM:** прогноз = средние токены/время/стоимость похожих
+   `done`-задач (`repo` + `track` ORCH-019, через read-only `usage.py`-агрегаты), bootstrap при пустой
+   истории; story-points — чистая функция-бакетизатор по `forecast_cost_usd` с конфигурируемыми порогами.
+4. **Запись в Plane (D6).** Прогноз story-points → `set_issue_estimate_point` (FK на estimate-point,
+   резолв `value→uuid`); факт → `set_issue_point` (устойчивый int); коммент → `add_comment`. Все под
+   `_guard_allows_write` (ORCH-117); отсутствие estimate-системы → best-effort пропуск + лог (NFR-7).
+5. **Персистентность (D7).** Новая аддитивная таблица `task_estimates` (`UNIQUE(work_item_id)`,
+   UPSERT-идемпотентность пере-оценки; `task_id` нуллабелен — issue на бэклоге). Фундамент петли калибровки
+   (ORCH-8).
+6. **Поверхности (D8).** Пункт «Оценка» (время·токены·стоимость) в общей Telegram-карточке
+   (`notifications`, never-raise, ORCH-087/095-совместимо).
+7. **Факт на `done` (D9).** Best-effort врезка в `stage_engine.advance_stage` (блок `next_stage=="done"`,
+   после terminal-sync): факт из `usage.py` → `set_actual` + `set_issue_point`; `estimate_point` не
+   перезаписывается.
+
+**Главное архитектурное решение — отказ от LLM-оценщика (D1).** Причины: NFR-5 (massive multi-select
+умножил бы LLM-вызовы и конкурировал бы за единственный транспорт `launcher._spawn` с боевыми агентами,
+рискуя обслуживанием enduro), NFR-4 (стоимость самой оценки), и политика ORCH-118 (размер задачи
+деривируем из tool-сигналов — суждение LLM не требуется). Контракт `estimate()` — граница расширения под
+будущий гибрид без переписывания вызывающих (но он сейчас НЕ строится).
+
+## Инварианты (нормативно)
+
+- **Оценка — наблюдатель/продюсер, НЕ Quality Gate и НЕ переход стадии.** `STAGE_TRANSITIONS` / реестр и
+  имена `QG_CHECKS` / семантика `check_*` / machine-verdict-ключи (`verdict:`/`result:`/`deploy_status:`/
+  `staging_status:`/`security_status:`/`coverage_status:`) / **схемы существующих таблиц** — **байт-в-байт
+  не тронуты**. Статус «Оценка» не добавляет ребра в машину стадий.
+- **Горячий путь не тронут:** `resolve_agent_model`/`resolve_agent_effort`/`_spawn` без изменений (Шаг 2
+  вне объёма — отдельный work item с зависимостью на ORCH-13).
+- **Схема БД:** ровно **одна** аддитивная таблица `task_estimates` (`CREATE TABLE IF NOT EXISTS`);
+  существующие таблицы не изменяются (NFR-8). Hot-path `claim_next_job`/очередь её не читают.
+- **Self-hosting-безопасность:** модуль только читает/пишет свою таблицу, читает usage-агрегаты и пишет в
+  Plane/Telegram — не деплоит, не рестартит прод-контейнер, не трогает `main`/force-push, без процессов.
+- **never-raise / обратимость:** все публичные функции и врезки изолированы; `estimator_enabled=false` /
+  доска без статуса «Оценка» / репо вне `estimator_repos` → байт-в-байт как до ORCH-020 (enduro и текущий
+  orchestrator не затронуты).
+- **Без kill-switch обхода write-guard:** записи `estimate_point`/`point`/коммент/состояние подчиняются
+  ORCH-117 (anti-drift: тест-процесс физически не пишет в боевой Plane).
+
+## Последствия
+
+Оператор получает прогноз для планирования бэклога одним массовым жестом; пере-оценка идемпотентна;
+заложен леджер прогноз↔факт под петлю калибровки (ORCH-8). Цена — net-new интеграция с Plane-estimate API
+(`estimate_point` — FK; смягчено best-effort/fail-safe + устойчивым int-`point`) и начальные пороги
+story-points (смягчено конфигурируемостью + леджером). Решение сознательно консервативно (детерминировано,
+обратимо, согласовано с ORCH-118) и **не требует** `arch:major-change` (аддитивный leaf по устоявшемуся
+паттерну, без новой стадии/правки таблиц/смены БД). Детали, альтернативы и риски —
+`docs/work-items/ORCH-020/06-adr/ADR-001-task-estimation-status-trigger.md`,
+`docs/work-items/ORCH-020/07-infra-requirements.md`, `08-data-requirements.md`, `10-tech-risks.md`.

docs/deployment/BUNDLED_SETUP.md

@@ -179,8 +179,8 @@ docker compose -f deploy/bundled/docker-compose.yml ps
 
 Доводка «одним запуском»: preflight → секреты → up/готовность → init Gitea
 (полностью автоматом: админ-бот + API-токен) → init Plane → онбординг
-sandbox-проекта **строго** кирпичом `onboard_project.py` (22 канонических
-статуса, включая fail-closed **`Confirm Deploy`** и **`STOP`**, лейблы,
+sandbox-проекта **строго** кирпичом `onboard_project.py` (23 канонических
+статуса, включая fail-closed **`Confirm Deploy`**, **`STOP`** и **`Оценка`**, лейблы,
 репо+webhook — golden source `docs/operations/ONBOARDING.md` §1) → git-доступ
 агентов → сборка `.env`/`.env.watchdog` → health.
 

docs/deployment/LITE_SETUP.md

@@ -206,12 +206,13 @@ curl -fsS "$ORCH_PLANE_API_URL/api/v1/workspaces/<workspace-slug>/projects/" \
 `ORCH_PLANE_API_TOKEN` в `.env`. Токен должен иметь право создавать проекты/статусы
 (нужно для `onboard_project.py apply`, §10).
 
-**5.3. Модель статусов — НЕ вручную.** Конвейеру нужны **22 канонических статуса** с
+**5.3. Модель статусов — НЕ вручную.** Конвейеру нужны **23 канонических статуса** с
 точными именами и группами; их создаёт `python3 scripts/onboard_project.py apply` (§10),
 полная таблица — `docs/operations/ONBOARDING.md` §1 (golden source; здесь не дублируется).
-Два имени фиксируем явно, потому что они **fail-closed** (без них ветка просто не
-активируется, без ошибки): **`Confirm Deploy`** (человеческий гейт прод-деплоя) и
-**`STOP`** (отмена задачи; обязан быть в группе `cancelled`).
+Три имени фиксируем явно, потому что они **fail-closed** (без них ветка просто не
+активируется, без ошибки): **`Confirm Deploy`** (человеческий гейт прод-деплоя),
+**`STOP`** (отмена задачи; обязан быть в группе `cancelled`) и **`Оценка`** (триггер
+оценки задачи, ORCH-020; группа `unstarted`/`backlog`, НЕ терминальная).
 
 ```bash
 # после §10 — проверить, что статусы созданы:
@@ -219,7 +220,7 @@ curl -fsS "$ORCH_PLANE_API_URL/api/v1/workspaces/<workspace-slug>/projects/<proj
   -H "X-API-Key: $ORCH_PLANE_API_TOKEN" | python3 -m json.tool | grep -c '"name"'
 ```
 
-**Проверка:** счётчик имён = 22 (или больше, если в проекте остались дефолтные статусы
+**Проверка:** счётчик имён = 23 (или больше, если в проекте остались дефолтные статусы
 Plane) и среди них `Confirm Deploy` и `STOP` — PASS.
 
 **5.4. Webhook + HMAC.** Приёмник — `POST https://<orchestrator-public-host>/webhook/plane`;
@@ -432,7 +433,7 @@ curl -fsS http://127.0.0.1:8501/health
 
 ## 10. Регистрация проекта заказчика
 
-Onboarding-CLI создаёт Plane-проект с 22 статусами и лейблами (`autoApprove` /
+Onboarding-CLI создаёт Plane-проект с 23 статусами и лейблами (`autoApprove` /
 `autoDeploy` / `Bug`), Gitea-репо с webhook'ом, скелет репо (kit) и печатает merged-реестр.
 Полный runbook — `docs/operations/ONBOARDING.md`; Lite-последовательность:
 

docs/operations/FAQ_STOP.md

@@ -0,0 +1,87 @@
+# FAQ: отмена задачи через статус STOP
+
+Эта страница — для пользователя доски Plane. Она объясняет простыми словами, что делает статус
+**STOP**, как им безопасно остановить задачу и чего от него ждать. Читать код для этого не нужно.
+
+Технические детали механизма — в
+[инженерном обзоре конвейера](../overview/tech-pipeline.md#отмена-stop--cancelled) и в
+[ADR ORCH-090](../work-items/ORCH-090/06-adr/ADR-001-stop-cancel-task.md) (источник истины
+поведения). Эта страница их **не дублирует**, а пересказывает «для человека» и ссылается на них.
+
+## Что делает статус STOP?
+
+STOP — это «кнопка отмены» задачи. Перевод задачи в статус STOP останавливает работу агента,
+снимает задачу с очереди, прибирает рабочие материалы (ветку и worktree) и помечает задачу
+отменённой (`cancelled`). Нажимать его безопасно даже посреди конвейера.
+
+## Как отменить задачу?
+
+Переведите issue в статус **STOP** на доске Plane — так же, как меняете любой другой статус.
+
+Предусловие: на доске должен быть заведён статус **STOP** (группа `cancelled`). Если его нет, STOP
+не сработает (см. раздел «Я нажал STOP, но ничего не произошло — почему?»).
+
+## Что происходит, когда я нажимаю STOP?
+
+По шагам:
+
+1. Активный агент **останавливается** (мягкая остановка процесса).
+2. Все **job'ы** этой задачи в очереди снимаются и больше не перезапускаются.
+3. Рабочая **ветка** задачи и её **worktree** удаляются. Ветка `main` и прод-контейнер при этом
+   никогда не трогаются.
+4. Задача переходит в терминальное состояние **`cancelled`**.
+5. Приходит уведомление в **Telegram** («🛑 … задача ОТМЕНЕНА (STOP)») и **комментарий в Plane**.
+
+При этом **документы задачи** (бизнес-запрос, анализ, ТЗ, ADR и т.д.) **сохраняются** — удаляются
+только рабочая ветка и worktree, не история документов.
+
+## Что если задача в этот момент сливается или деплоится?
+
+Если STOP пришёл во время **необратимого шага** (слияние в `main` или выкладка в прод), отмена
+**аккуратно откладывается** до честного завершения этого шага. Вы увидите уведомление вида
+«⏸️ … отмена ОТЛОЖЕНА». Ветка `main` и прод при этом не трогаются; как только шаг честно
+завершится, отмена применяется автоматически.
+
+Иными словами: STOP **не прерывает** уже начатый необратимый шаг на полпути — он дожидается его
+честного завершения, а затем отменяет задачу.
+
+## Откатит ли STOP уже выложенный код?
+
+**Нет.** STOP сбрасывает **незавершённый прогресс** задачи (рабочую ветку, worktree, очередь), но
+**не откатывает** код, который уже влит в `main` или выложен в прод. Откат уже выложенного —
+это отдельная задача (revert), и STOP её **не делает**.
+
+## Как перезапустить отменённую задачу?
+
+Отменённую задачу **нельзя «продолжить с середины»**. Чтобы начать заново, переведите её в статус
+**«To Analyse»** — задача будет создана **с нуля**: новая ветка от актуального `main`, новый анализ
+и полный проход конвейера.
+
+## Я нажал STOP, но ничего не произошло — почему?
+
+Вероятные причины:
+
+- На доске **нет статуса STOP** — переход не распознаётся (безопасный no-op). Заведите статус STOP
+  (группа `cancelled`) и попробуйте снова.
+- Задача **уже завершена или уже отменена** — повторный STOP ничего не меняет (это нормально,
+  идемпотентный no-op, задача не ломается).
+- Отмена **отключена для репозитория** настройкой оператора (`stop_status_enabled` /
+  `stop_status_repos`) — обратитесь к оператору.
+
+## Где увидеть, что задача отменена?
+
+- **Карточка задачи в Telegram** покажет «🛑 … ОТМЕНЕНА (STOP)».
+- В **Plane** появится комментарий об отмене.
+- Оператор может увидеть отмену на служебной странице состояния `GET /queue` — в блоке `stop`.
+
+## STOP, Approved и Confirm Deploy — в чём разница?
+
+Это разные управляющие статусы, их легко перепутать:
+
+- **STOP** — *отменить* задачу и сбросить её незавершённый прогресс.
+- **Approved** — *одобрить* артефакт анализа (двигает задачу дальше по конвейеру); деплой он **не**
+  запускает.
+- **Confirm Deploy** — *подтвердить* выкладку в прод.
+
+Подробнее об управляющих статусах и их семантике — в
+[инженерном обзоре конвейера](../overview/tech-pipeline.md). Эта страница описывает только STOP.

docs/operations/ONBOARDING.md

@@ -46,7 +46,7 @@ hooks под выбранным owner (`--gitea-owner`, дефолт из кон
 
 1. **Проект**: создаётся с `identifier = --prefix`. Уже существует → передай
    `--plane-project-id <uuid>` (ensure распознает и пропустит).
-2. **Статусы — точные канонические имена** (22, источник — `plane_sync._PLANE_NAME_TO_KEY`;
+2. **Статусы — точные канонические имена** (23, источник — `plane_sync._PLANE_NAME_TO_KEY`;
    опечатка = тихая деградация fail-closed веток):
 
    | Статус | Группа | | Статус | Группа |
@@ -62,9 +62,11 @@ hooks под выбранным owner (`--gitea-owner`, дефолт из кон
    | Review | `started` | | **STOP** | **`cancelled`** |
    | Testing | `started` | | Awaiting Deploy | `started` |
    | Deploying | `started` | | Monitoring after Deploy | `started` |
+   | **Оценка** | **`unstarted`** | | | |
 
    ⚠️ Код-критично: `STOP` обязан быть в группе `cancelled` (иначе ветка отмены молча не
-   активируется); в терминальных группах (`completed`/`cancelled`) — ТОЛЬКО
+   активируется); **`Оценка`** (триггер оценки задачи, ORCH-020) — группа `unstarted`/`backlog`,
+   **НЕ** терминальная; в терминальных группах (`completed`/`cancelled`) — ТОЛЬКО
    Done/Cancelled/STOP, иначе terminal-detection ложно сочтёт живую задачу терминальной.
 3. **Лейблы**: `autoApprove`, `autoDeploy`, `Bug` (имена — из конфига оркестратора; их
    отсутствие = fail-safe ручной режим / полный цикл).
@@ -149,7 +151,7 @@ hooks под выбранным owner (`--gitea-owner`, дефолт из кон
      --webhook-url https://openclaw.mva154.duckdns.org/orchestrator/webhook/gitea
    ```
 
-   Проверяет: запись реестра парсится и совпадает по полям; все 22 статуса резолвятся
+   Проверяет: запись реестра парсится и совпадает по полям; все 23 статуса резолвятся
    (включая fail-closed `Confirm Deploy`/`STOP`); лейблы на месте; webhook существует и
    активен; kit-файлы в репо (6 промптов, `AGENTS.md`, `INFRA.md`, `_templates`/`_standards`);
    нет неразрешённых плейсхолдеров. Любой gap → exit `2` с перечнем.

docs/overview/business.md

@@ -42,6 +42,10 @@
   аналитики и отдельной стадии проектирования, но через все те же гейты качества.
 - **Отмена задачи одной кнопкой.** Перевод задачи в статус «STOP» в трекере останавливает
   работу, снимает её с очереди и прибирает за собой — безопасно даже посреди конвейера.
+- **Оценка задачи до запуска.** Перевод задачи в статус «Оценка» в трекере даёт прогноз её
+  стоимости, времени и сложности (story points) по истории похожих задач — можно оценить
+  сразу пачку задач и спланировать, что и когда брать в работу. По завершении задачи рядом
+  с прогнозом ложится факт — оценки калибруются на реальных данных.
 - **Наблюдаемость.** У каждой задачи — живая карточка в Telegram (стадия, время, стоимость);
   у платформы — служебные страницы состояния и машинные метрики; история отклонений пишется
   в журнал уроков.
@@ -97,6 +101,13 @@
 Передумали — переводите задачу в статус «STOP»: работа агента останавливается, ветка и
 рабочие материалы прибираются, задача помечается отменённой. Если задача в этот момент в
 необратимой фазе выкладки — отмена аккуратно откладывается до её честного завершения.
+Подробнее — [FAQ по статусу STOP](../operations/FAQ_STOP.md).
+
+### Сценарий 7: оценить бэклог перед планированием
+Оператор выделяет несколько задач в бэклоге и переводит их в статус «Оценка». По каждой
+платформа считает прогноз стоимости, времени и сложности по истории завершённых задач и
+возвращает задачу в бэклог с проставленной оценкой и комментарием. Видно, что дорого, а что
+дёшево — и чем наполнить ближайший прогон. По завершении задачи рядом ляжет факт.
 
 ---
 

docs/overview/presentation.md

@@ -71,7 +71,7 @@
 
 - Запуск: перевод задачи в статус «To Analyse» — единственная точка входа в конвейер
 - Статусы Plane — индикация, а не управление: платформа выставляет их сама (Backlog → … → Done)
-- Управляющих статусов ровно три: запуск, человеческие гейты и отмена
+- Статусы-действия, на которые платформа реагирует: запуск, человеческие гейты, отмена (STOP) и оценка задачи («Оценка»)
 - Ход задачи виден сразу: статусы доски, живая карточка в Telegram, комментарии в задаче со ссылками на ветку и PR
 
 > Визуал: доска Plane с движущейся карточкой и зеркальное уведомление в Telegram
@@ -83,6 +83,7 @@
 - Лейблы «autoApprove» / «autoDeploy» снимают эти два решения для пакетного авто-режима
 - Авто-режим убирает только ожидание человека — ни одна техническая проверка не пропускается
 - Лейбл «Bug» — короткий багфикс-маршрут; статус «STOP» — безопасная отмена с уборкой ветки и worktree, не трогает прод
+- Статус «Оценка» — прогноз стоимости, времени и сложности задачи (можно пачкой) с возвратом в бэклог, без запуска LLM
 
 > Визуал: две кнопки человека, переключатели авто-лейблов и стоп-кран STOP
 
@@ -137,6 +138,7 @@
 - Пакет задач на ночь: метки авто-одобрения, утром всё на проде
 - Багфикс по короткому маршруту с обязательным регресс-тестом
 - Остановить задачу: статус STOP — безопасная отмена с уборкой
+- Оценить бэклог: пачка задач в статус «Оценка» — прогноз и возврат в бэклог
 - Несколько проектов параллельно без пересечений
 
 > Визуал: пять пиктограмм-сценариев

docs/overview/tech-data-model.md

@@ -49,6 +49,7 @@ deploy-лога; манифест — [PIPELINE_DOCS](../_standards/PIPELINE_DOC
 | `tracker_messages` | леджер всех Telegram-карточек задачи (зачистка сирот) |
 | `lessons` | машинный журнал уроков — структурированные отклонения конвейера |
 | `transition_lease` | durable-владение side-effectful переходом стадии: один владелец на задачу, liveness по pid+boot-id (предотвращает двойное применение необратимых эффектов) |
+| `task_estimates` | леджер прогноз↔факт оценки задачи (стоимость/время/токены/story points), ключ `work_item_id` — фундамент калибровки оценок |
 
 Все изменения схемы — аддитивные и идемпотентные (`CREATE TABLE IF NOT EXISTS`, ensure-column
 при старте): обновление платформы не требует ручных миграций.

docs/overview/tech-integrations.md

@@ -8,13 +8,15 @@
 - **Вход конвейера:** перевод задачи в статус «To Analyse» — единственная точка запуска
   пайплайна. Вебхуки Plane (HMAC-подписанные) доставляют изменения задач.
 - **Статусы = индикация, не управление** ([блок 2](tech-pipeline.md)): платформа сама
-  выставляет статусы доски, чтобы человек видел осмысленную картину; управляют конвейером
-  только машина стадий и три управляющих статуса (запуск, человеческие гейты, STOP).
+  выставляет статусы доски, чтобы человек видел осмысленную картину; саму машину стадий не
+  подменяет ни один статус. Платформа реагирует лишь на **операторские статусы-действия**:
+  запуск, человеческие гейты (Approved/Confirm Deploy), STOP (отмена) и «Оценка» (прогноз
+  задачи с возвратом в Backlog).
 - **Лейблы** — декларативные переключатели на задаче: `autoApprove` / `autoDeploy` (снятие
   человеческих гейтов), `Bug` (багфикс-маршрут). Источник истины — Plane API: ошибка чтения
   лейблов трактуется как «лейбла нет» (fail-safe — никогда не «авто» по ошибке).
 - Платформа пишет в задачу комментарии о ходе работ (под ботами ролей) с кликабельными
-  ссылками на ветку/PR.
+  ссылками на ветку/PR; для оценённых задач — прогноз (в поле оценки) и факт по завершении.
 
 ## Gitea — git, PR, CI
 

docs/overview/tech-observability.md

@@ -12,6 +12,7 @@
 - стоимость задачи нарастающим итогом (токены/доллары по каждому запуску агента);
 - честные метрики времени на финише: время агентов / время ожидания человека / общее
   календарное — три независимые цифры, а не одна вводящая в заблуждение сумма;
+- пункт «Оценка» (прогноз стоимости · времени · токенов), если задача оценивалась;
 - кликабельный номер задачи (ведёт в Plane), отметка багфикс-маршрута.
 
 Карточка тихая (без пингов); пингуют только алерты: красный гейт, ожидание решения человека,
@@ -21,7 +22,8 @@
 
 - **`GET /queue`** — человекочитаемый снимок всего конвейера: очередь и job'ы, состояние
   serial gate (заморозки, паузы задач, причина ожидания успешника), авто-лейблы, багфикс-трек,
-  coverage, журнал уроков, владение переходами (`transition_lease`), фоновые демоны. Первая
+  coverage, журнал уроков, владение переходами (`transition_lease`), оценки задач (`estimator`),
+  фоновые демоны. Первая
   точка диагностики «что сейчас происходит». Паузу/возобновление задачи в serial gate включают
   два источника: **оператор** — явными эндпоинтами `POST /serial-gate/pause|resume`, и **движок** —
   автоматически, когда аналитик задаёт блокирующие вопросы и задача уходит в Needs Input (авто-park;

docs/overview/tech-pipeline.md

@@ -126,12 +126,27 @@ freeze, ни объявленные зависимости. Свежесть б
 (идёт слияние/выкладка) — отмена откладывается и применяется после честного завершения шага.
 STOP никогда не трогает `main` и прод-контейнер.
 
+Пользовательская инструкция «как этим пользоваться» — [FAQ по статусу STOP](../operations/FAQ_STOP.md).
+
+## Оценка задачи: статус «Оценка»
+
+Перевод backlog-задачи в статус **«Оценка»** (в т.ч. **массово** — multi-select Plane)
+запускает прогноз её стоимости, времени, токенов и сложности (story points `1/2/3/5/8`) по
+истории похожих завершённых задач — детерминированной эвристикой, **без запуска LLM**. Прогноз
+пишется в поле оценки задачи, публикуется комментарием и пунктом «Оценка» в Telegram-карточке,
+после чего задача **возвращается в Backlog**. Это операторский side-жест: он **не двигает задачу
+по конвейеру** (не ребро `STAGE_TRANSITIONS`), не занимает слот очереди и не выдёргивает
+in-flight работу. Пере-оценка — повторный перевод в «Оценка» (идемпотентно). По завершении самой
+задачи рядом с прогнозом сохраняется **факт** — фундамент калибровки оценок.
+
 ## Статусная модель Plane: индикация ≠ управление
 
 Статусы в Plane — слой **индикации**: они показывают человеку осмысленную картину хода задачи,
-но никогда не управляют конвейером (машина стадий — только `STAGE_TRANSITIONS`). Управляющих
-статусов ровно три: запуск в работу, Approved/Confirm Deploy (человеческие гейты) и STOP
-(отмена). Полная карта статусов — в [инженерном справочнике](../architecture/README.md).
+но никогда не управляют конвейером (машина стадий — только `STAGE_TRANSITIONS`). Отдельно стоят
+**операторские статусы-действия**, на которые платформа реагирует: запуск в работу,
+Approved/Confirm Deploy (человеческие гейты), STOP (отмена) и «Оценка» (прогноз с возвратом в
+Backlog, см. выше). Они инициируют действие или снимают ожидание человека, но саму машину стадий
+не подменяют. Полная карта статусов — в [инженерном справочнике](../architecture/README.md).
 
 ---
 

docs/work-items/ORCH-020/00-business-request.md

@@ -0,0 +1,7 @@
+# Business Request: Оценка задачи: стоимость, время и сложность (адаптивный выбор моделей)
+
+Work Item ID: ORCH-020
+
+## Description
+
+Оценка задачи: стоимость, время и сложность (для адаптивного выбора моделей)Цель: добавить оркестратору функцию ОЦЕНКИ задачи — прогноз стоимости и времени реализации. Шаг 2: оценка СЛОЖНОСТИ задачи для адаптивного выбора моделей агентов.📊 Шаг 1 — Оценка стоимости и времениПеред запуском (или на этапе аналитики) оркестратор прогнозирует: сколько будет стоить задача (токены × тариф = $) и сколько займёт времени.Данные уже есть: учёт токенов и cost_usd по прошлым задачам (наблюдаемость из PR #20). ET-014 ~35 мин — есть фактура для калибровки.База оценки — история похожих задач (по типу/стадиям/стеку): средние токены/время/стоимость.Где показывать: коммент в Plane / Telegram-уведомление при заведении задачи — Слава видит прогноз до старта.Post-factum: сравнение прогноз vs факт → уточнение модели оценки (петля, связь с ORCH-8 саморазвитие).🧠 Шаг 2 — Оценка сложности → адаптивный выбор моделейКлассификация сложности задачи (trivial / small / medium / complex) на этапе триажа/аналитики.На основе сложности — адаптивно выбирать модель агента: простая задача → дешёвая/быстрая модель; сложная → сильная модель. Прямая связь с ORCH-13 (мультипровайдерность).Оптимизация: не жечь дорогую модель на тривиальной правке (экономия), но не недокормить сложную задачу слабой моделью (качество).Сложность также влияет на выбор трека (связь с ORCH-19 багфикс: trivial → hotfix, complex → полный цикл).🔧 Что проработатьСигналы для оценки сложности: текст постановки, тип (фича/баг), затронутые файлы/стек, исторические аналоги.Кто оценивает: отдельный шаг-оценщик, под-функция аналитика, или эвристика на входе.Модель оценки: эвристика по истории / отдельный LLM-вызов-оценщик / гибрид.Точность vs стоимость самой оценки (оценка не должна стоить дороже экономии).Маппинг сложность → модель (конфигурируемый, связь с ORCH-13 и манифестом проекта ORCH-9).🔗 СвязкиORCH-13 (мультипровайдерность) — оценка сложности кормит адаптивный выбор модели. Тесная пара.ORCH-19 (багфикс-трек) — сложность определяет глубину пайплайна.ORCH-8 (саморазвитие) — петля прогноз vs факт уточняет модель оценки.PR #20 (наблюдаемость, токены/cost_usd) — фактура для калибровки.❓ Открытые вопросы СлавеГде показывать прогноз стоимости/времени — Telegram при заведении, Plane-коммент, оба?Оценка обязательна для каждой задачи или по запросу/для крупных?Адаптивный выбор модели — автоматический по сложности, или с твоим подтверждением для дорогих?Шкала сложности — фиксированная (trivial/small/medium/complex) или числовая (story points)?Создано 2026-06-04. Статус: Backlog, на проработку. Источник: голосовая постановка Славы + раскладка Стрим.

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

@@ -0,0 +1,238 @@
+---
+work_item: ORCH-020
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-17
+model_used: claude-opus-4-8
+---
+
+# 01 — BRD (бизнес-требования): ORCH-020 — Оценка задачи (прогноз стоимости/времени/story points), запускаемая статусом «Оценка»
+
+Work Item: **ORCH-020** · Repo: **orchestrator** · Стадия: analysis
+
+> **Revision после REJECT (Plane, 2026-06-17).** Заказчик отклонил предыдущий пакет: «**что я не
+> увидел в БРД — как запускать оценку?** Я хотел бы переводить задачу в статус "Оценка", после чего
+> запускался бы механизм оценки, и после завершения оценки задача бы меняла статус на backlog. На
+> оценку я буду отправлять задачи **массово через Plane**. Также я могу **переоценивать задачи много
+> раз**.» Этот раунд **переписывает модель триггера**: оценка теперь — **операторское действие,
+> запускаемое выделенным Plane-статусом «Оценка»** (а не «автоматически для каждой задачи на
+> `start_pipeline`», как в отклонённой версии). Прочие требования (что прогнозируем, куда пишем,
+> леджер прогноз↔факт, leaf-инварианты) сохранены и согласованы с новым триггером. Полный пакет
+> `01`–`04` supersede’ит прежний по mtime.
+
+## 1. Бизнес-контекст и проблема
+
+Заказчик планирует работу по бэклогу вручную и хочет **до отправки задачи в работу** видеть прогноз:
+сколько задача будет стоить (токены × тариф = $), сколько займёт времени и насколько она сложна
+(размер в story points). Сейчас этих данных до старта нет: оркестратор собирает фактуру
+(`input_tokens`/`output_tokens`/`cache_*`/`cost_usd`/`model`/`effort`, тайминги
+`agent_runs.started_at/finished_at`, `tasks.created_at/updated_at`) **только постфактум** через
+`src/usage.py` (`task_usage_summary`, `agent_cost_totals`, `record_usage`). Контур **прогноза до
+старта** отсутствует.
+
+**Корень REJECT — отсутствовал способ ЗАПУСКА оценки.** Заказчик мыслит оценку как **операторский
+жест в Plane**, а не как невидимый авто-шаг: он сам решает, какие задачи бэклога оценить, **массово**
+переводит их в выделенный статус, получает прогнозы и продолжает планирование. Отклонённая версия
+прятала триггер в `start_pipeline` («оценка обязательна для каждой задачи автоматически») и явно
+называла точку триггера «реализационной деталью» — это и есть то, что заказчик «не увидел» и
+отверг.
+
+Цитаты заказчика (Plane, 2026-06-17):
+- REJECT: «как запускать оценку? Я хотел бы **переводить задачу в статус "Оценка"**, после чего
+  запускался бы механизм оценки, и после завершения оценки задача бы **меняла статус на backlog**. На
+  оценку я буду отправлять задачи **массово через Plane**. Также я могу **переоценивать задачи много
+  раз**.»
+- Раунд Needs Input: «В Plane есть поле оценка, туда и нужно записывать оценку. По факту завершения
+  задачи вписать в смежное поле… для оценки есть два поля.»; «Только Шаг 1, без выбора модели»;
+  «Модели не выбираем и не меняем. Это вне скоупа».
+
+Установленные факты по коду (на которые опирается решение, не изобретать):
+- **Прецедент «статус-триггер уже есть в платформе.** Plane-статусы — слой B (индикация, ORCH-066) и
+  НЕ управляют машиной стадий; но платформа уже имеет **операторские action-статусы**, запускающие
+  side-механизмы: **STOP** (ORCH-090, отмена задачи) и **Confirm Deploy** (ORCH-059, прод-деплой).
+  Оба разбираются в `webhooks/plane.py::handle_issue_updated` через
+  `proj_states.get("<key>")` и оба **намеренно отсутствуют** в `plane_sync._DEFAULT_STATES`
+  (fail-closed: доска без статуса → `None` → ветка не активируется). Статус «Оценка» — **третий
+  представитель этого же семейства**.
+- **Маппинг имени статуса → логический ключ** — `plane_sync._PLANE_NAME_TO_KEY` (`"STOP"→"stop"`,
+  `"Confirm Deploy"→"confirm_deploy"`); `get_project_states` резолвит UUID статуса per-project из
+  Plane API.
+- **Массовость — «бесплатно».** Plane multi-select по N задачам в статус «Оценка» порождает N
+  отдельных `issue.updated`-вебхуков (по одному на issue); каждый обрабатывается независимо. Отдельный
+  «batch-UX» в оркестраторе не требуется — массовость обеспечивает сам Plane.
+- **Фактура для калибровки уже накоплена** (`agent_runs`, агрегаты `task_usage_summary` /
+  `agent_cost_totals`, тайминги). Это сырьё для «истории похожих задач».
+- **Plane-поля существуют.** На issue присутствуют поля `estimate_point` (ОЦЕНКА) и `point` (ФАКТ);
+  estimate-система на проекте (`project.estimate`) на момент анализа **не настроена** — инфра-
+  предусловие (NFR-7).
+- **Выбор модели/эффорта статичен по роли** (`resolve_agent_model`/`resolve_agent_effort`,
+  ORCH-41/74; дефолт `claude-opus-4-8`) и в этой задаче **не трогается** (Шаг 2 вне объёма).
+- **leaf-паттерн платформы** (`serial_gate`/`coverage_gate`/`labels`/`lessons`/`cancel`): never-raise,
+  kill-switch `*_enabled`, `*_repos` CSV (пусто → self-hosting only), read-only блок в `GET /queue`.
+
+## 2. Объём (scope)
+
+### В объёме (Шаг 1 — Оценка, запускаемая статусом)
+- **Триггер «Оценка» (ядро правки).** Перевод issue в выделенный Plane-статус **«Оценка»** запускает
+  механизм оценки этой задачи. Оператор делает это **вручную и массово** (multi-select в Plane).
+- **Жизненный цикл статуса:** `Backlog → (оператор) «Оценка» → [оркестратор: оценка] → (оркестратор)
+  Backlog`. По завершении оценки оркестратор **сам возвращает** issue в статус **`Backlog`**.
+- **Пере-оценка много раз.** Повторный перевод в «Оценка» переоценивает задачу заново (идемпотентно:
+  перезапись `estimate_point` и строки леджера). Применимо при изменении скоупа.
+- **Прогноз четырёх величин:** стоимость ($), время, токены и **сложность в story points** из
+  фиксированной шкалы `{1, 2, 3, 5, 8}`.
+- **Шкала story points (фиксированная, ответ Q-3 = вариант A):** `1` — мелкая docs/label/config;
+  `2` — небольшой фикс; `3` — средняя; `5` — сложная (код + тесты); `8` — эпик / разбивать.
+- **Запись прогноза в Plane-поле `estimate_point`** (это ОЦЕНКА).
+- **Запись факта в Plane-поле `point`** по завершении задачи (фактическая реализованная сложность в
+  story points из фактических токенов/времени/стоимости по той же шкале) — для калибровки.
+- **Отображение прогноза на двух поверхностях** (ответ Q-5 = оба): Plane-коммент + пункт **«Оценка»**
+  в общей Telegram-карточке задачи (`src/notifications.py`) — **время, токены, стоимость**.
+- **Локальный леджер прогноз↔факт** (фундамент петли калибровки, связь с ORCH-8): хранение прогноза,
+  факта и дельты, **ключ — `work_item_id`** (issue может ещё не иметь pipeline-задачи на момент
+  оценки — она на бэклоге).
+
+### Вне объёма
+- **Шаг 2 — адаптивный выбор моделей агентов** (ответы Q-1/Q-2: «Только Шаг 1, без выбора модели»;
+  «Модели не выбираем и не меняем. Это вне скоупа»). Горячий путь `resolve_agent_model`/
+  `resolve_agent_effort`/`_spawn` **не модифицируется**.
+  > **ACTION (поручение заказчика, Plane 16:34):** «заведи отдельную задачу в Plane для адаптивного
+  > выбора модели и укажи зависимость на мультипровайдеров (ORCH-13)». Создание Plane-issue — действие
+  > уровня заказчика/PM и **вне write-объёма аналитика** (Write ограничен `docs/work-items/<id>/*`).
+  > Фиксирую как обязательный follow-up: новый work item «Адаптивный выбор модели агента по сложности»
+  > с зависимостью на **ORCH-13**; оценщик сложности из ORCH-020 — его вход. Оператору: подтвердить
+  > создание или создать вручную.
+- **Автопереключение трека по сложности** (связка с ORCH-19) — позже; здесь сложность лишь
+  вычисляется и публикуется как сигнал.
+- **Авто-ретроспективщик / RICE-приоритизатор** (E2/E3 ORCH-8) — вне объёма; леджер — фундамент.
+- **Автоматическая оценка КАЖДОЙ задачи на `start_pipeline`** — **исключена явно** (модель
+  отклонённой версии). Оценка — операторский on-demand жест через статус «Оценка».
+- **Изменение тарифной/биллинговой модели** — используется существующий `cost_usd` из `usage.py`.
+- **Новый «batch-UX»/массовый эндпоинт как ОСНОВНОЙ путь** — не нужен (массовость даёт Plane
+  multi-select → N вебхуков). Программный `POST /estimate*` допустим лишь как **опциональное**
+  удобство/диагностика, не как основной триггер (см. TRZ §4).
+
+## 3. Заинтересованные стороны
+- **Заказчик / владелец продукта (Слава)** — инициатор оценки (переводит задачи в «Оценка»),
+  потребитель прогноза для планирования бэклога; принимает результат.
+- **Оркестратор (self-hosting)** — носитель функции; общий прод обслуживает и `enduro-trails`.
+- **Будущая петля саморазвития (ORCH-8)** — потребитель леджера прогноз↔факт для калибровки.
+- **ORCH-13 (мультипровайдерность)** — будущий потребитель сигнала сложности (через follow-up Шаг 2).
+
+## 4. Бизнес-требования (BR)
+
+### Триггер и жизненный цикл (ядро ревизии)
+- **BR-T1 — Запуск оценки статусом «Оценка».** Перевод issue в выделенный Plane-статус **«Оценка»**
+  запускает оценку именно этой задачи. Это **единственный обязательный** способ запуска (массовый и
+  ручной), реализуемый по образцу операторских action-статусов STOP (ORCH-090) / Confirm Deploy
+  (ORCH-059).
+- **BR-T2 — Авто-возврат в Backlog.** По завершении оценки (успех или best-effort-пропуск)
+  оркестратор **сам** переводит issue обратно в статус **`Backlog`**. Заказчик видит задачу
+  вернувшейся в бэклог с заполненным `estimate_point`.
+- **BR-T3 — Массовость через Plane.** Массовый перевод N задач в «Оценка» (multi-select Plane)
+  оценивает все N; каждый issue обрабатывается независимо (N вебхуков). Отдельный массовый UX в
+  оркестраторе не требуется.
+- **BR-T4 — Пере-оценка много раз (идемпотентно).** Повторный перевод задачи в «Оценка»
+  переоценивает её заново; прогноз и строка леджера **перезаписываются** (не дублируются). Число
+  пере-оценок не ограничено.
+- **BR-T5 — Fail-closed статус.** На доске без статуса «Оценка» (enduro / частичная конфигурация /
+  Plane недоступен) триггер **не активируется** (ключ резолвится в `None`) — нулевая регрессия;
+  это инфра-предусловие (NFR-7), а не ошибка.
+- **BR-T6 — Не нарушать машину стадий и in-flight работу.** Статус «Оценка» запускает **side-
+  механизм**, а не переход стадии. Если у issue есть **активная** pipeline-задача (queued/running
+  job), триггер — **no-op + лог** (не выдёргивать выполняемую работу в Backlog, не трогать
+  `STAGE_TRANSITIONS`). Авто-возврат в Backlog **не** создаёт цикла: статус `Backlog` ни одной веткой
+  `handle_issue_updated` не обрабатывается (no-op-эхо).
+
+### Содержание оценки (сохранено, согласовано с триггером)
+- **BR-1 — Прогноз.** Для задачи оркестратор производит прогноз четырёх величин: **стоимость ($)**,
+  **время**, **токены** и **сложность в story points** из фиксированной шкалы `{1,2,3,5,8}`.
+- **BR-2 — База оценки — история.** Прогноз строится на истории похожих **завершённых** задач (по
+  типу/стадиям/стеку): средние токены/время/стоимость из уже накопленной фактуры (`agent_runs`,
+  `task_usage_summary`, `agent_cost_totals`, тайминги). При отсутствии истории — разумный bootstrap-
+  дефолт (не блокирует).
+- **BR-3 — Шкала story points фиксированная** с точной семантикой `1/2/3/5/8` (см. §2). Значение `8` —
+  «эпик: разбивать».
+- **BR-4 — On-demand, не блокирующая.** Оценка производится **по запросу** (перевод в «Оценка»), а не
+  для каждой задачи автоматически; строго best-effort — сбой/выключение оценки **никогда** не тормозит
+  конвейер и не меняет маршрут.
+- **BR-5 — Доступность до старта работы.** Поскольку оператор оценивает задачи на **бэклоге** (до
+  `To Analyse`/`start_pipeline`), прогноз доступен **до** перевода задачи в работу — он и нужен для
+  планирования отправки задач.
+- **BR-7 — Запись прогноза в Plane.** Прогноз сложности (story points) записывается в поле issue
+  **`estimate_point`** (= ОЦЕНКА).
+- **BR-8 — Запись факта в Plane.** По завершении задачи (переход в `done`) фактическая реализованная
+  сложность (story points из фактических токенов/времени/стоимости по той же шкале) записывается в
+  смежное поле **`point`** — для калибровки; прогноз `estimate_point` при этом **не перезаписывается**.
+- **BR-9 — Отображение на двух поверхностях.** Прогноз публикуется: (a) **Plane-комментом**;
+  (b) пунктом **«Оценка»** в общей Telegram-карточке задачи — **время, токены, стоимость**.
+- **BR-10 — Леджер прогноз↔факт (калибровка).** Прогноз и факт сохраняются локально вместе с дельтой
+  (ключ `work_item_id`); фундамент петли уточнения модели оценки (связь с ORCH-8). Достаточно
+  фиксировать обе величины и дельту (авто-уточнение модели — позже).
+
+## 5. Нефункциональные требования (NFR)
+- **NFR-1 — Оценка ≠ Quality Gate / ≠ переход стадии.** Модуль — наблюдатель/продюсер.
+  `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict-ключи (`verdict:`/`result:`/
+  `deploy_status:`/`staging_status:`/`security_status:`/`coverage_status:`) / схемы **существующих**
+  таблиц — **байт-в-байт не тронуты**. Статус «Оценка» не добавляет ребра в машину стадий; он
+  запускает side-механизм и сам возвращает issue в Backlog.
+- **NFR-2 — leaf-паттерн.** never-raise (любой сбой → warning + безопасный дефолт), kill-switch
+  `*_enabled`, скоуп `*_repos` (CSV; **пусто → self-hosting only**), read-only блок в `GET /queue`.
+- **NFR-3 — self-hosting safety.** Модуль не рестартит/не роняет прод-контейнер, не трогает `main`/
+  force-push, **не вмешивается в горячий путь запуска агентов** (`resolve_agent_model`/
+  `resolve_agent_effort`/`_spawn` не модифицируются). Выключенный флаг / неприменимый репо → нулевая
+  регрессия для `enduro-trails` и `orchestrator`.
+- **NFR-4 — Стоимость оценки ≪ её ценности.** Сама оценка должна быть дешёвой и быстрой относительно
+  выгоды планирования. Выбор механизма (эвристика по истории / отдельный LLM-вызов / гибрид) и баланс
+  «точность vs стоимость» — **архитектурное** решение (`06-adr`); в TRZ — лишь требование-ограничение.
+- **NFR-5 — Толерантность к массовости.** Массовый перевод (десятки задач разом → десятки вебхуков
+  почти одновременно) **не должен** перегружать прод/конвейер: оценка best-effort, изолирована от
+  control-path; механизм сглаживания нагрузки (дешёвая эвристика / очередь / троттлинг) — деталь
+  `06-adr`. Требование: bulk не роняет и не тормозит обслуживание других проектов.
+- **NFR-6 — Запись в Plane через существующие примитивы.** `estimate_point`/`point`/коммент/возврат в
+  Backlog пишутся через `plane_sync` и подчиняются sandbox write-guard (ORCH-117): в боевом рантайме
+  (`uvicorn`) — штатная запись, из тест/worktree-процесса — заблокирована. **Новых секретов/токенов не
+  вводится.**
+- **NFR-7 — Fail-safe и инфра-предусловия Plane.** (a) Статус **«Оценка»** должен существовать на
+  доске проекта (его отсутствие = fail-closed no-op, BR-T5). (b) estimate-система Plane со значениями
+  `1/2/3/5/8` (Fibonacci) для `estimate_point` должна быть настроена; при её отсутствии запись
+  `estimate_point`/`point` **best-effort пропускается** (+ лог) и **не роняет** конвейер. Детали и
+  точные группы статуса — `07-infra-requirements.md` (архитектор).
+- **NFR-8 — Обратная совместимость данных.** Хранение прогноз↔факт — **аддитивная** новая таблица
+  (`CREATE TABLE IF NOT EXISTS`); существующие таблицы/колонки не изменяются.
+
+## 6. Допущения и ограничения
+- Оценка на бэклоге работает по **issue** (описание/тип/лейблы из Plane API + история похожих), а не
+  по локальной pipeline-задаче: на момент оценки `tasks`-строки может **не быть** → леджер и запись
+  ключуются по `work_item_id`, `task_id` — нуллабелен до старта пайплайна.
+- Статус «Оценка» — транзиентный (issue в нём лишь на время оценки, затем Backlog); его Plane-группа
+  (`backlog`/`unstarted`) косметична — деталь онбординга/инфры (ORCH-009 расширяется на 23-й статус).
+- Фактура `usage.py`/`agent_runs` достаточна для расчёта факта при завершении; «фактические story
+  points» выводятся из факта по той же шкале `{1,2,3,5,8}`.
+- Без ORCH-13 «выбор модели» бессмыслен (один дефолт) — Шаг 2 корректно вынесен в follow-up.
+- Точная Plane-семантика `estimate_point` (FK на estimate-point estimate-системы) vs `point`
+  (целочисленный) — деталь реализации/инфры (архитектор + NFR-7).
+
+## 7. Критерии успеха
+Заказчик **массово переводит** задачи бэклога в статус **«Оценка»**; по каждой оркестратор
+производит прогноз (стоимость/время/токены/story points), пишет его в `estimate_point`, публикует в
+Plane-комменте и пункте «Оценка» Telegram-карточки, сохраняет в леджер прогноз↔факт и **возвращает
+issue в Backlog**; пере-оценка повтором перевода идемпотентна; по завершении задачи факт пишется в
+`point`. Всё это — без единого изменения control-path/гейтов, без касания горячего пути запуска
+агентов, без выдёргивания in-flight работы; на доске без статуса «Оценка» / при выключенном флаге —
+нулевая регрессия. Детальные PASS/FAIL — `03-acceptance-criteria.md`.
+
+## 8. Риски
+- **Статус «Оценка» дёргает in-flight задачу** → снимается BR-T6 (no-op при активном job) + авто-
+  возврат только в Backlog, никогда не трогая стадии.
+- **Цикл вебхуков** (возврат в Backlog → новый webhook) → снимается тем, что `Backlog` не
+  обрабатывается ни одной веткой `handle_issue_updated` (no-op-эхо) — анти-loop по построению.
+- **Перегрузка от массового перевода** → снимается NFR-5 (best-effort, дешёвый механизм/сглаживание —
+  `06-adr`).
+- **Запись в боевой Plane** (`estimate_point`/`point`/коммент/состояние) на общей доске → снимается
+  write-guard (ORCH-117) + best-effort/fail-safe (NFR-6/NFR-7).
+- **Неточность прогноза на холодном старте** (мало истории) → bootstrap-дефолт + петля калибровки
+  (BR-10).
+- **Расползание в Шаг 2** (control-path) → жёсткий out-of-scope + NFR-3.
+Детальный разбор — `10-tech-risks.md` (архитектор).

docs/work-items/ORCH-020/01-questions.md

@@ -0,0 +1,132 @@
+---
+work_item: ORCH-020
+stage: analysis
+author_agent: analyst
+status: needs-input
+created_at: 2026-06-17
+model_used: claude-opus-4-8
+---
+
+# 01 — Открытые вопросы (Open Questions): ORCH-020 — Оценка задачи: стоимость, время и сложность (адаптивный выбор моделей)
+
+Work Item: **ORCH-020** · Repo: **orchestrator** · Стадия: analysis
+
+> **Сигнальный** when-applicable артефакт (ORCH-120, adr-0053). Пишется аналитиком ТОЛЬКО при
+> **блокирующей** неоднозначности, когда выпустить корректные 4 deliverables (`01-brd`/`02-trz`/
+> `03-acceptance-criteria`/`04-test-plan`) нельзя без ответа заказчика. **Не** machine-verdict;
+> гейтом не парсится — сигнал движку (`_handle_analysis_approved_flow`) увести задачу в **Needs
+> Input**. После ответов в Plane аналитик перезапускается (resume), читает свежие комментарии и
+> выпускает полный пакет.
+
+## 1. Контекст
+
+Бизнес-запрос (`00-business-request.md`) ставит **две связанные, но разные по риску** функции и
+**сам перечисляет 4 нерешённых вопроса для Славы** («❓ Открытые вопросы Славе»). Это решения
+уровня владельца продукта, а не аналитические дефолты: они определяют **объём**, **модель данных**
+и — главное — затрагивается ли **прод-control-path выбора модели агента** на self-hosting инстансе,
+который из ОДНОГО процесса с ОБЩЕЙ БД обслуживает и `enduro-trails`.
+
+**Что установлено по фактическому коду (карта src/, на которую опираются вопросы):**
+
+- **Фактура для оценки уже есть, но только post-run.** `src/usage.py` парсит токены/`cost_usd`/
+  модель из вывода Claude CLI ПОСЛЕ финиша агента; `agent_runs` несёт `input_tokens`/`output_tokens`/
+  `cache_*`/`cost_usd`/`model`/`effort`; есть агрегаты `task_usage_summary`/`agent_cost_totals` и
+  тайминги (`agent_runs.started_at/finished_at`, `tasks.created_at/updated_at/brd_review_*`).
+  → **Прогноз ДО старта** как контур сейчас отсутствует — это новый продюсер, не правка гейта.
+- **Выбор модели/эффорта статичен по роли.** `resolve_agent_model`/`resolve_agent_effort`
+  (`src/agents/launcher.py`, ORCH-41/74) резолвят модель из config/project-override и применяют её в
+  `_spawn` (`--model`/`--effort`, launch-стамп ORCH-109). **Хука «варьировать модель по сложности
+  задачи нет».** Любой адаптивный per-task override — это вмешательство в горячий путь запуска
+  агентов на общем проде.
+- **ORCH-13 (мультипровайдерность) ещё не реализован.** Дефолт один — `claude-opus-4-8`; реально
+  различимы лишь **тиры эффорта** (`low/medium/high/xhigh/max`). Без ORCH-13 «выбор модели»
+  фактически вырождается в «выбор эффорта».
+- **`tasks.track` (ORCH-019) уже существует** (`'full'|'bug'`) — связка «сложность → трек»
+  опирается на готовый механизм, отдельной модели данных под трек не требует.
+- **`lessons` (ORCH-098)** — журнал ОТКЛОНЕНИЙ, НЕ леджер «прогноз vs факт»: готовой калибровочной
+  основы под петлю прогноз↔факт (связь с ORCH-8) пока нет.
+- **Leaf-паттерн** (`serial_gate`/`coverage_gate`/`labels`/`lessons`): never-raise, kill-switch
+  `*_enabled`, `*_repos` CSV (**пусто → self-hosting only**), read-only блок в `GET /queue`. Любой
+  новый модуль оценки обязан ему следовать — это ограничение, а не предмет вопроса.
+
+Без ответов ниже корректные BR/TRZ/AC/тест-план выпустить нельзя: для пунктов Q-2/Q-3 существуют
+**взаимоисключающие** варианты спецификации (разные AC, разная модель данных, разный контракт), а
+Q-1 определяет, какие из «Шаг 1 / Шаг 2» вообще входят в этот work item.
+
+## 2. Блокирующие вопросы
+
+> Q-1…Q-4 — жёсткие блокеры. Q-5 — вопрос самого Славы с безопасным дефолтом (включён, чтобы
+> закрыть все его вопросы за один раунд Needs Input и не плодить второй цикл).
+
+- **Q-1 — Объём и очерёдность: ORCH-020 = «Шаг 1 + Шаг 2» сразу, или «Шаг 1 сейчас» + «Шаг 2 после
+  ORCH-13»?**
+  - Вариант A *(рекомендуемый)*: **Шаг 1 (прогноз стоимости/времени) сейчас**; Шаг 2 (адаптивный
+    выбор модели) — отдельным work item ПОСЛЕ ORCH-13, т.к. без мультипровайдерности «выбор модели»
+    сводится к выбору эффорта, а сам по себе оценщик сложности можно поставлять как сигнал.
+  - Вариант B: **оба шага в одном work item** — тогда оценщик сложности обязан выдавать решение,
+    готовое кормить адаптивный выбор уже сейчас (на тирах эффорта, до ORCH-13).
+  - Вариант C: **только Шаг 2** (классификация сложности + маппинг), прогноз стоимости/времени — позже.
+  - Почему блокирует: определяет, выпускаю ли я deliverables на Шаг 2 вообще и какие BR/AC в них
+    попадут. Объём — зона аналитика, угадывать его нельзя.
+
+- **Q-2 — Адаптивный выбор модели: автоматический по сложности, или с твоим подтверждением для
+  «дорогих»/нетривиальных?** *(вопрос Славы №3; самый критичный — self-hosting safety)*
+  - Вариант A *(рекомендуемый)*: **advisory-only** — оценщик лишь предлагает класс/модель (коммент +
+    карточка), фактический `resolve_agent_model` НЕ трогается; смена модели — ручной/конфиг-шаг.
+    Прод-control-path неизменен, риск для `enduro-trails` нулевой.
+  - Вариант B: **авто-override на self-hosting только** — per-task выбор модели/эффорта применяется
+    автоматически, под kill-switch, скоуп `*_repos` пустой = только `orchestrator`, никогда не влияет
+    на чужой репозиторий и на уже запущенные задачи.
+  - Вариант C: **авто для дешёвых тиров, подтверждение для дорогих** (порог по прогнозу $/сложности).
+  - Почему блокирует: A и B/C — это **разные спецификации** (advisory ⇒ AC про коммент/карточку и
+    отсутствие правок горячего пути; auto ⇒ AC про безопасный gated override, скоуп, инвариант «не
+    трогает enduro и in-flight»). Невозможно написать корректные FR/AC, не зная, ввязываемся ли мы в
+    прод-путь запуска агентов на общем проде.
+
+- **Q-3 — Шкала сложности: фиксированные категории (`trivial/small/medium/complex`) или числовая
+  (story points)?** *(вопрос Славы №4)*
+  - Вариант A *(рекомендуемый)*: **фиксированные категории** (как в постановке) — простая модель
+    данных (`tasks.complexity TEXT`, аддитивно по паттерну `tasks.track`), прозрачный маппинг
+    «класс → эффорт/модель/трек».
+  - Вариант B: **числовая** (story points / 1–N) — гибче для калибровки, но требует решить пороги
+    отображения и маппинг диапазон→модель.
+  - Вариант C: **гибрид** (число внутри + ярлык-категория для людей).
+  - Почему блокирует: задаёт контракт выхода оценщика, тип новой колонки и форму маппинга
+    «сложность → модель/трек». Это часть требований (модель данных), не реализационная деталь.
+
+- **Q-4 — Оценка обязательна для КАЖДОЙ задачи, или по запросу / только для крупных?** *(вопрос Славы №2)*
+  - Вариант A *(рекомендуемый)*: **для каждой задачи автоматически** на входе/в аналитике
+    (`start_pipeline`), но строго never-raise/best-effort — сбой оценки никогда не тормозит конвейер.
+  - Вариант B: **по запросу** (эндпоинт/лейбл Plane) и/или только при превышении порога размера.
+  - Вариант C: **только self-hosting `orchestrator`** на первом этапе (обкатка), enduro — позже.
+  - Почему блокирует: определяет точку интеграции (триггер в `start_pipeline` для всех проектов
+    общего прода vs опциональный путь) и формулировку NFR про область раската и обратимость.
+
+- **Q-5 — Где показывать прогноз стоимости/времени: Telegram при заведении, Plane-коммент, оба?**
+  *(вопрос Славы №1; мягкий — есть безопасный дефолт)*
+  - Вариант A *(рекомендуемый дефолт)*: **оба** — Plane-коммент (`plane_sync.add_comment`) +
+    live-карточка/уведомление в Telegram (`notifications.send_telegram`); это безопасный суперсет
+    поверх уже существующих поверхностей.
+  - Вариант B: только Telegram. Вариант C: только Plane-коммент.
+  - Почему (мягко) блокирует: влияет на объём (одна поверхность vs две) и на AC отображения; если
+    промолчишь — зафиксирую дефолт A.
+
+## 3. Что разблокирует анализ
+
+- **Ответы на Q-1…Q-4** (и подтверждение/override Q-5) комментарием в Plane к ORCH-020.
+- Минимально для старта достаточно: **Q-1** (объём), **Q-2** (advisory vs auto — определяет, трогаем
+  ли control-path) и **Q-3** (шкала). Q-4/Q-5 имеют безопасные дефолты (A), которые я приму при
+  молчании.
+- На **resume**: прочту свежие комментарии-ответы и (а) если все блокеры сняты — выпущу **полный**
+  валидный пакет из 4 файлов (он автоматически supersede’ит этот файл по mtime, повторного Needs
+  Input не будет); (б) если часть вопросов осталась — **перепишу** этот файл, оставив только
+  актуальные блокеры (снова Needs Input). Устаревшие вопросы вперемешку с новыми оставлять не буду.
+
+> Подразумеваемые инварианты, которые я зафиксирую в пакете при ЛЮБЫХ ответах (не вопросы — границы):
+> новый функционал следует leaf-паттерну (never-raise, kill-switch, `*_repos` пусто → self-hosting
+> only, блок в `GET /queue`); `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict-ключи/схемы
+> существующих таблиц — не трогаются (оценка — наблюдатель/продюсер, **не** Quality Gate); прод-
+> контейнер не рестартится; `main`/force-push не затрагиваются. Выбор механизма оценки (эвристика по
+> истории / LLM-оценщик / гибрид) и «точность vs стоимость самой оценки» — **архитектурное** решение
+> (06-adr), его я не предрешаю; в TRZ зафиксирую лишь требование-ограничение «стоимость оценки ≪
+> ожидаемой экономии».

docs/work-items/ORCH-020/02-trz.md

@@ -0,0 +1,166 @@
+---
+work_item: ORCH-020
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-17
+model_used: claude-opus-4-8
+---
+
+# 02 — ТЗ (TRZ): ORCH-020 — Оценка задачи, запускаемая Plane-статусом «Оценка»
+
+Work Item: **ORCH-020** · Repo: **orchestrator** · Стадия: analysis
+
+> ТЗ описывает **конкретные изменения к реализации**, выведенные из BRD и фактического кода.
+> Архитектурное обоснование/решения (выбор механизма оценки эвристика vs LLM vs гибрид, точные
+> сигнатуры врезок, индексы, формулы маппинга, сглаживание массовой нагрузки, Plane-группа статуса
+> «Оценка») — задача архитектора (`06-adr`).
+
+## 1. Сводка изменения
+
+Вводится **новый операторский Plane-статус «Оценка»** — триггер механизма оценки (по образцу
+action-статусов **STOP**/ORCH-090 и **Confirm Deploy**/ORCH-059). Перевод issue в «Оценка»
+(в т.ч. **массово** через Plane multi-select) запускает **новый leaf-модуль оценки**
+(`src/estimator.py`, never-raise), который прогнозирует **стоимость / время / токены / сложность
+(story points `{1,2,3,5,8}`)** на основе истории завершённых задач (агрегаты `src/usage.py`).
+Прогноз: (a) пишется в Plane-поле `estimate_point`, (b) публикуется Plane-комментом, (c) добавляется
+пунктом «Оценка» (время/токены/стоимость) в общую Telegram-карточку, (d) сохраняется в **новой
+аддитивной таблице** `task_estimates` (леджер прогноз↔факт, ключ `work_item_id`). По завершении
+оценки оркестратор **возвращает issue в статус `Backlog`**. По завершении самой задачи (переход в
+`done`) **факт** пишется в Plane-поле `point`. Пере-оценка — повтор перевода в «Оценка»
+(идемпотентно).
+
+**Инвариант (NFR-1/NFR-3):** оценка — наблюдатель/продюсер, **не** Quality Gate и **не** переход
+стадии. `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict-ключи / схемы существующих
+таблиц — байт-в-байт; горячий путь `resolve_agent_model`/`resolve_agent_effort`/`_spawn` — не
+трогается. Статус «Оценка» не добавляет ребра в машину стадий.
+
+## 2. Задействованные модули / пути
+| Путь | Действие |
+|------|----------|
+| `src/plane_sync.py` | **изменить** — (1) `_PLANE_NAME_TO_KEY += {"Оценка": "estimate"}`; ключ `estimate` **НЕ добавлять** в `_DEFAULT_STATES` (fail-closed, как `stop`/`confirm_deploy`); (2) новые write-хелперы `set_issue_estimate_point(work_item, value)`, `set_issue_point(work_item, value)`, `set_issue_backlog(work_item)` (все через guard `_guard_allows_write`, ORCH-117); (3) read-хелпер текущих полей `estimate_point`/`point`. fail-safe при отсутствии estimate-конфига |
+| `src/webhooks/plane.py` | **изменить** — в `handle_issue_updated` добавить **fail-closed ветку** `estimate_state = proj_states.get("estimate")` → `handle_estimate(data, project_id)` (распознаётся как **отдельный** жест, не алиасит stop/to_analyse/confirm_deploy/approved/rejected). Новый `handle_estimate`: резолв issue (pipeline-задачи может не быть), guard `estimator.applies(repo)`, guard «нет активного job» (BR-T6), запуск оценки, затем `set_issue_backlog` |
+| `src/estimator.py` | **создать** — leaf: `estimate(work_item_id, issue|description, repo)` → прогноз `{tokens,seconds,cost_usd,story_points}`; маппинг величин → story-point bucket `{1,2,3,5,8}` (чистая функция); расчёт факта из `usage.py`; `applies(repo)`, `should_estimate(task|None)` (анти-disruption), `snapshot()`; never-raise |
+| `src/db.py` | **изменить** — аддитивная таблица `task_estimates` (`CREATE TABLE IF NOT EXISTS` в `init_db()`) + хелперы `record_estimate`/`set_actual`/`get_estimate`/`estimates_snapshot`; существующие таблицы/колонки не трогать |
+| `src/usage.py` | **переиспользовать** (read-only) — `task_usage_summary`/`agent_cost_totals`/тайминги для **факта**; при необходимости тонкий read-only агрегат «история похожих задач» |
+| `src/notifications.py` | **изменить** — пункт «Оценка» (время · токены · стоимость) в рендере общей карточки; never-raise, пустой прогноз → пункт опускается |
+| `src/main.py` | **изменить** — (опц.) `POST /estimate?work_item=<id>` / `POST /estimate/backlog` как программное удобство; **read-only блок `estimator` в `GET /queue`** |
+| `src/config.py` | **изменить** — флаги (см. §7) |
+| `tests/test_orch020_estimator.py` | **создать** — покрытие (см. `04-test-plan.yaml`) |
+
+## 3. Функциональные требования
+
+### FR-T1 — Статус «Оценка» как триггер (BR-T1, BR-T5)
+`_PLANE_NAME_TO_KEY["Оценка"] = "estimate"`; ключ `estimate` **отсутствует** в `_DEFAULT_STATES`.
+В `handle_issue_updated` — отдельная ветка: `estimate_state = proj_states.get("estimate")`;
+`if estimate_state and new_state == estimate_state: await handle_estimate(...)`. Доска без статуса →
+`estimate_state is None` → ветка инертна (fail-closed, зеркало `stop`/`confirm_deploy`). Ветка не
+должна аннулировать/перехватывать STOP/`to_analyse`/`confirm_deploy`/approved/rejected (UUID
+«Оценка» отличен от всех; порядок ветки выбирает архитектор, инвариант — взаимоисключение жестов).
+
+### FR-T2 — Обработчик `handle_estimate` (BR-T1, BR-T6)
+`handle_estimate(data, project_id)`: резолвит `plane_id`/`work_item_id`; `repo` определяется по
+проекту. Guard-цепочка (все — no-op-with-log при невыполнении, never-raise):
+1. `estimator.applies(repo)` — kill-switch + скоуп (False → no-op);
+2. **анти-disruption (BR-T6):** если у issue есть pipeline-задача с **активным** job
+   (`has_active_job_for_task`) → no-op + лог (не выдёргивать in-flight работу). Issue без задачи
+   (бэклог) или с терминальной/idle-задачей → оценка допустима.
+Далее: `estimator.estimate(...)` → запись прогноза (FR-T3) → **`set_issue_backlog(work_item)`**
+(BR-T2). Контракт never-raise: любая ошибка логируется, вебхук-флоу не падает.
+
+### FR-T3 — Прогноз задачи (BR-1, BR-2, BR-3)
+`estimator.estimate(work_item_id, description|issue, repo)` возвращает `{forecast_tokens,
+forecast_seconds, forecast_cost_usd, story_points}`, `story_points ∈ {1,2,3,5,8}`. База — история
+похожих **завершённых** задач (средние токены/время/стоимость из `usage.py`-агрегатов); пустая
+история → bootstrap-дефолт. Маппинг величин → bucket — чистая функция (пороги — `06-adr`).
+never-raise: сбой → безопасный дефолт + warning.
+
+### FR-T4 — Семантика story points (BR-3)
+Шкала фиксированная: `1` docs/label/config · `2` небольшой фикс · `3` средняя · `5` сложная
+(код+тесты) · `8` эпик/разбивать. Значения вне набора не выдаются.
+
+### FR-T5 — Авто-возврат в Backlog + анти-loop (BR-T2, BR-T6)
+После оценки `handle_estimate` зовёт `set_issue_backlog(work_item)` → issue возвращается в `Backlog`.
+Это **не** создаёт цикла: `Backlog`-UUID не совпадает ни с одной триггер-веткой `handle_issue_updated`
+(`stop`/`to_analyse`/`confirm_deploy`/`approved`/`rejected`/`estimate`) → входящий webhook «state →
+Backlog» = no-op-эхо. Возврат best-effort: сбой записи статуса не роняет флоу (прогноз уже записан).
+
+### FR-T6 — Массовость и пере-оценка (BR-T3, BR-T4)
+Массовый перевод N задач в «Оценка» = N независимых `issue.updated`-вебхуков → N вызовов
+`handle_estimate` (никакого спец-batch-кода). Пере-оценка = повторный перевод: `estimate`
+идемпотентно **перезаписывает** прогноз в `task_estimates` (UPSERT по `work_item_id`) и
+`estimate_point`; дублей строк нет.
+
+### FR-T7 — Запись прогноза и факта в Plane (BR-7, BR-8, NFR-6, NFR-7)
+- Прогноз story points → `set_issue_estimate_point` → поле issue `estimate_point`.
+- По завершении задачи (переход в `done`, врезка в существующий done-путь): из `usage.py` считается
+  факт (токены/время/стоимость) → маппится в story-point bucket → `set_issue_point` → поле `point`;
+  `estimate_point` не перезаписывается.
+- Все записи через `plane_sync` под guard ORCH-117; отсутствие estimate-конфига/поля → best-effort
+  пропуск + лог (не падать).
+
+### FR-T8 — Отображение (BR-9)
+- **Plane-коммент** с прогнозом (стоимость/время/токены/story points) — `plane_sync.add_comment`.
+- **Telegram-карточка** — пункт **«Оценка»**: время · токены · стоимость (`notifications`).
+Обе поверхности — best-effort, не блокируют конвейер.
+
+### FR-T9 — Леджер прогноз↔факт (BR-10)
+`task_estimates` хранит прогноз (на момент оценки) и факт (на момент `done`) + дельту, ключ
+`work_item_id` (т.к. на момент оценки `task_id` может быть `NULL` — issue на бэклоге). Фундамент
+калибровки (ORCH-8); авто-уточнение модели в объём не входит.
+
+### FR-T10 — leaf-инварианты (NFR-2, NFR-3)
+`applies(repo)` = `estimator_enabled` ∧ скоуп `estimator_repos` (пусто → self-hosting only),
+проверяется локально и ПЕРВЫМ (без сети). Выключено → весь модуль инертен (нулевая регрессия:
+статус «Оценка» не обрабатывается, ничего не пишется). read-only блок `estimator` в `GET /queue`
+(флаг/скоуп/счётчики прогнозов/записей/возвратов-в-Backlog).
+
+## 4. Изменения API
+| Метод/путь | Назначение |
+|------------|-----------|
+| **Plane-статус «Оценка»** (не HTTP-эндпоинт) | **Основной триггер**: перевод issue в статус → `handle_estimate`. Массовость — multi-select Plane. |
+| `POST /estimate?work_item=<id>` *(опц.)* | Программно произвести/обновить прогноз одной задачи (то же ядро, что статус-триггер) — удобство/диагностика, не основной путь |
+| `POST /estimate/backlog` *(опц.)* | Программно оценить backlog-задачи проекта — удобство; основной массовый путь — статус «Оценка» |
+| `GET /estimate?work_item=<id>` *(опц.)* | Прочитать текущий прогноз vs факт из `task_estimates` |
+| `GET /queue` | **+ read-only блок `estimator`**; existing-поля не меняются |
+
+Существующие эндпоинты/контракты не изменяются. Webhook-контракт `issue.updated` не меняется —
+добавляется лишь распознавание ещё одного целевого статуса.
+
+## 5. Изменения схемы БД
+**Новая аддитивная таблица** `task_estimates` (`CREATE TABLE IF NOT EXISTS`, без правки существующих):
+`work_item_id` (ключ/UPSERT-цель) · `task_id` (нуллабелен до старта пайплайна) · `repo` · прогноз
+(`forecast_tokens`, `forecast_seconds`, `forecast_cost_usd`, `forecast_story_points`) · факт
+(`actual_tokens`, `actual_seconds`, `actual_cost_usd`, `actual_story_points`) · дельта (`delta_*`
+или вычисляемая) · `source` (`status`/`manual`/`api`) · `estimate_count` (число пере-оценок,
+опц.) · `created_at` · `updated_at`. Точные типы/индексы/уникальность (UNIQUE по `work_item_id`
+для идемпотентного UPSERT) — `06-adr`. Существующие таблицы (`tasks`/`agent_runs`/`jobs`/…) — **не
+изменяются** (NFR-8).
+
+## 6. Требования к новым/изменённым QG checks
+**Нет.** Оценка — наблюдатель/продюсер, не Quality Gate; статус «Оценка» — операторский side-триггер,
+не ребро `STAGE_TRANSITIONS`. `QG_CHECKS` / `check_*` / machine-verdict-ключи / `STAGE_TRANSITIONS` —
+**не трогаются**. Новых номерных артефактов pipeline (`NN-*.md`) и новых вердикт-парсеров нет (оценка
+публикуется в Plane/Telegram/`task_estimates`, не во frontmatter-гейтах).
+
+## 7. Совместимость / регресс
+- **Флаги** (`config.py`, дефолты безопасные): `estimator_enabled` (kill-switch, env
+  `ORCH_ESTIMATOR_ENABLED`), `estimator_repos` (CSV, env `ORCH_ESTIMATOR_REPOS`; **пусто →
+  self-hosting only**). Доп. тюнинг (bootstrap-дефолты, пороги bucket, целевой возврат-статус,
+  сглаживание массовой нагрузки) — конфиг-ключи на усмотрение `06-adr`.
+- **Откат** = `ORCH_ESTIMATOR_ENABLED=false` → модуль инертен: статус «Оценка» не обрабатывается
+  (`applies`=False до сети), ни записи в Plane, ни строки карточки, ни обращений к таблице; конвейер
+  байт-в-байт до ORCH-020. Доп. откат «на уровне доски» — не создавать статус «Оценка» (fail-closed,
+  BR-T5).
+- **Область раската:** по умолчанию self-hosting `orchestrator`; `enduro-trails` не затронут (скоуп
+  `estimator_repos` пуст + на его доске статуса «Оценка» нет → fail-closed).
+- **never-raise / fail-safe:** все публичные функции и врезки изолированы (`try/except` → warning +
+  безопасный дефолт). Сбой оценки/записи в Plane/возврата статуса/рендера карточки — не роняет
+  конвейер (NFR-2/6/7).
+- **Анти-disruption / анти-loop:** активный job → no-op (BR-T6); возврат в Backlog — no-op-эхо
+  (FR-T5). Машина стадий и in-flight задачи не затрагиваются.
+- **Горячий путь не тронут:** `resolve_agent_model`/`resolve_agent_effort`/`_spawn` — без изменений
+  (NFR-3).
+- **Инфра-предусловия (NFR-7):** (a) статус **«Оценка»** на доске проекта (онбординг ORCH-009 →
+  23-й статус; группа — `06-adr`/`07-infra-requirements.md`); (b) estimate-система Plane
+  (`1/2/3/5/8`) для `estimate_point`; их отсутствие → fail-closed/best-effort пропуск, не падение.

docs/work-items/ORCH-020/03-acceptance-criteria.md

@@ -0,0 +1,221 @@
+---
+work_item: ORCH-020
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-17
+model_used: claude-opus-4-8
+---
+
+# 03 — Критерии приёмки (Acceptance Criteria): ORCH-020 — Оценка задачи, запускаемая статусом «Оценка»
+
+Work Item: **ORCH-020** · Repo: **orchestrator** · Стадия: analysis
+
+Формат: каждый критерий имеет **PASS** (что должно быть истинно для приёмки) и **FAIL** (что
+считается провалом). Reviewer/тестер проверяет их буквально по файлам репозитория и поведению.
+
+---
+
+## AC-T1 — Запуск оценки статусом «Оценка» (ядро ревизии)
+
+**Условие:** перевод issue в Plane-статус «Оценка» запускает оценку этой задачи.
+- **PASS:** `_PLANE_NAME_TO_KEY` содержит `"Оценка" → "estimate"`; `handle_issue_updated` имеет
+  отдельную ветку `proj_states.get("estimate")` → `handle_estimate(...)`; при переводе issue в
+  «Оценка» вызывается оценка (прогноз вычислен и записан).
+- **FAIL:** триггера-статуса нет; оценка по-прежнему авто-запускается на каждой задаче в
+  `start_pipeline`; ветка «Оценка» аннулирует/перехватывает STOP/`to_analyse`/`confirm_deploy`/
+  approved/rejected.
+
+---
+
+## AC-T2 — Авто-возврат в Backlog
+
+**Условие:** по завершении оценки issue возвращается в статус `Backlog`.
+- **PASS:** после записи прогноза `handle_estimate` вызывает `set_issue_backlog(work_item)` и issue
+  оказывается в `Backlog`; возврат best-effort (сбой записи статуса не роняет флоу, прогноз уже
+  записан).
+- **FAIL:** issue остаётся в «Оценка»/ином статусе; возврат отсутствует; сбой возврата роняет вебхук.
+
+---
+
+## AC-T3 — Массовость через Plane
+
+**Условие:** массовый перевод задач в «Оценка» оценивает их все.
+- **PASS:** N задач, переведённых в «Оценка» (multi-select Plane → N `issue.updated`-вебхуков),
+  дают N независимых вызовов `handle_estimate`; каждая получает прогноз; спец-batch-кода для этого не
+  требуется.
+- **FAIL:** часть задач не оценивается; обработка зависит от несуществующего «batch-режима»; один
+  webhook гасит остальные.
+
+---
+
+## AC-T4 — Пере-оценка много раз (идемпотентно)
+
+**Условие:** повторный перевод в «Оценка» переоценивает задачу без дублей.
+- **PASS:** повтор обновляет прогноз в `task_estimates` (UPSERT по `work_item_id`) и `estimate_point`;
+  строка одна, не дублируется; число пере-оценок не ограничено.
+- **FAIL:** повтор создаёт дубль строки в `task_estimates`; повтор игнорируется/падает.
+
+---
+
+## AC-T5 — Fail-closed статус «Оценка»
+
+**Условие:** на доске без статуса «Оценка» триггер не активируется.
+- **PASS:** `estimate` отсутствует в `_DEFAULT_STATES`; на проекте без статуса
+  `proj_states.get("estimate") is None` → ветка инертна (нет KeyError, нет оценки); enduro-trails не
+  затронут.
+- **FAIL:** `estimate` добавлен в `_DEFAULT_STATES`; отсутствие статуса даёт KeyError/ошибку; чужой
+  репо триггерится.
+
+---
+
+## AC-T6 — Анти-disruption in-flight + анти-loop
+
+**Условие:** статус «Оценка» — side-механизм, не трогает выполняемую работу и не зацикливается.
+- **PASS:** issue с активным (queued/running) job → `handle_estimate` = no-op + лог (in-flight работа
+  не выдёргивается в Backlog, стадии не трогаются); возврат в `Backlog` — no-op-эхо (`Backlog`-UUID не
+  совпадает ни с одной триггер-веткой → входящий webhook ничего не запускает).
+- **FAIL:** активную задачу выдёргивает в Backlog/прерывает; возврат в Backlog порождает повторный
+  запуск оценки (цикл); меняется `STAGE_TRANSITIONS`.
+
+---
+
+## AC-1 — Прогноз четырёх величин
+
+**Условие:** `estimator.estimate(...)` возвращает прогноз стоимости, времени, токенов и сложности.
+- **PASS:** структура с `forecast_cost_usd`, `forecast_seconds`, `forecast_tokens` и `story_points`,
+  `story_points ∈ {1,2,3,5,8}`; пустая история → bootstrap-дефолт (не исключение).
+- **FAIL:** отсутствует любая из четырёх величин; `story_points` вне `{1,2,3,5,8}`; функция бросает
+  исключение при отсутствии истории.
+
+---
+
+## AC-2 — Фиксированная семантика story points
+
+**Условие:** маппинг величин → story-point bucket соответствует шкале заказчика.
+- **PASS:** значения и смысл строго `1` (docs/label/config) · `2` (небольшой фикс) · `3` (средняя) ·
+  `5` (сложная код+тесты) · `8` (эпик/разбивать); чистая функция маппинга покрыта unit-тестом.
+- **FAIL:** иные значения/градации (`4`, `7`, свободное число) или произвольная числовая шкала.
+
+---
+
+## AC-3 — Запись прогноза в Plane `estimate_point`
+
+**Условие:** прогноз story points записывается в поле issue `estimate_point`.
+- **PASS:** при оценке вызывается `set_issue_estimate_point` (через `plane_sync`/guard ORCH-117); при
+  настроенной estimate-системе значение оказывается в `estimate_point`.
+- **FAIL:** прогноз пишется в `point` (перепутаны поля), не пишется, либо запись обходит guard.
+
+---
+
+## AC-4 — Запись факта в Plane `point` по завершении
+
+**Условие:** по завершении задачи (переход в `done`) факт пишется в смежное поле `point`.
+- **PASS:** на `done` факт вычисляется из `usage.py` (токены/время/стоимость), маппится в story-point
+  bucket и пишется в `point`; `estimate_point` не перезаписывается.
+- **FAIL:** факт пишется в `estimate_point`, не пишется, либо затирает прогноз.
+
+---
+
+## AC-5 — Пункт «Оценка» в Telegram-карточке
+
+**Условие:** общая карточка задачи показывает прогноз.
+- **PASS:** в карточке присутствует пункт **«Оценка»** с **временем, токенами и стоимостью**; пустой
+  прогноз → пункт опускается (never-raise); инвариант «одна карточка на задачу» не нарушен.
+- **FAIL:** пункт отсутствует; его рендер роняет/ломает карточку; нарушен инвариант одной карточки.
+
+---
+
+## AC-6 — Plane-коммент с прогнозом
+
+**Условие:** прогноз публикуется комментом в Plane.
+- **PASS:** постится коммент со стоимостью/временем/токенами/story points (best-effort, через
+  `add_comment`).
+- **FAIL:** коммент не постится при включённом флаге на применимом репо без причины в логе.
+
+---
+
+## AC-7 — Программные эндпоинты (опциональны, не основной триггер)
+
+**Условие:** программный путь, если реализован, использует то же ядро.
+- **PASS:** `POST /estimate?work_item=<id>` / `POST /estimate/backlog` (если есть) дают тот же
+  результат, что статус-триггер (UPSERT в `task_estimates` + `estimate_point` + коммент + карточка),
+  идемпотентны; их отсутствие не нарушает приёмку (основной путь — статус «Оценка»).
+- **FAIL:** эндпоинт расходится с поведением статус-триггера; преподносится как ЕДИНСТВЕННЫЙ способ
+  запуска (триггер-статуса нет).
+
+---
+
+## AC-8 — On-demand + доступность до старта, best-effort
+
+**Условие:** оценка запускается по требованию (статус), доступна до старта работы и никогда не
+блокирует конвейер.
+- **PASS:** оценка идёт по переводу в «Оценка» на бэклоге (до `To Analyse`/`start_pipeline`); при
+  сбое оценки конвейер не затрагивается (best-effort, лог-warning); НЕ авто-обязательна на каждой
+  задаче.
+- **FAIL:** оценка — блокирующий шаг (сбой тормозит/меняет маршрут); оценка авто-навязана каждой
+  задаче на `start_pipeline`.
+
+---
+
+## AC-9 — leaf-инварианты (kill-switch / скоуп / GET /queue)
+
+**Условие:** модуль следует leaf-паттерну.
+- **PASS:** `estimator_enabled=false` → модуль полностью инертен (статус «Оценка» не обрабатывается,
+  нет записей в Plane/карточку/таблицу); `estimator_repos` пуст → активен только на self-hosting
+  `orchestrator`; есть read-only блок `estimator` в `GET /queue`; все публичные функции never-raise.
+- **FAIL:** при выключенном флаге что-то пишется/меняется; enduro-trails затронут при пустом скоупе;
+  нет блока в `GET /queue`; функция бросает наружу.
+
+---
+
+## AC-10 — Control-path и гейты не тронуты (NFR-1/NFR-3)
+
+**Условие:** оценка ничего не меняет в машине стадий и горячем пути.
+- **PASS:** `git diff` не затрагивает `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, machine-verdict-
+  ключи и схемы существующих таблиц; `resolve_agent_model`/`resolve_agent_effort`/`_spawn` — без
+  изменений; статус «Оценка» не добавлен как ребро стадий; зелёный анти-регресс существующих тестов.
+- **FAIL:** любое из перечисленного изменено; маршрут задачи зависит от результата оценки.
+
+---
+
+## AC-11 — Шаг 2 (выбор модели) вне объёма
+
+**Условие:** адаптивный выбор модели не реализуется.
+- **PASS:** нет кода, выбирающего/меняющего модель/эффорт по сложности; в `01-brd.md` зафиксирован
+  out-of-scope + follow-up на отдельный work item с зависимостью на ORCH-13.
+- **FAIL:** добавлена логика per-task override модели/эффорта; follow-up не зафиксирован.
+
+---
+
+## AC-12 — Леджер прогноз↔факт + fail-safe записи
+
+**Условие:** прогноз и факт сохраняются; запись в Plane fail-safe.
+- **PASS:** `task_estimates` (новая аддитивная таблица, ключ `work_item_id`, `task_id` нуллабелен)
+  хранит прогноз, факт и дельту; при ненастроенной estimate-системе Plane запись `estimate_point`/
+  `point` best-effort пропускается с логом, конвейер не падает.
+- **FAIL:** существующая схема БД изменена; отсутствие estimate-конфига роняет оценку/конвейер.
+
+---
+
+## Сводная матрица AC ↔ FR/BR
+| AC | Покрывает |
+|----|-----------|
+| AC-T1 | BR-T1, BR-T5 / FR-T1 |
+| AC-T2 | BR-T2 / FR-T5 |
+| AC-T3 | BR-T3 / FR-T6 |
+| AC-T4 | BR-T4 / FR-T6 |
+| AC-T5 | BR-T5 / FR-T1 |
+| AC-T6 | BR-T6 / FR-T2, FR-T5 |
+| AC-1 | BR-1, BR-2 / FR-T3 |
+| AC-2 | BR-3 / FR-T4 |
+| AC-3 | BR-7 / FR-T7 |
+| AC-4 | BR-8 / FR-T7 |
+| AC-5 | BR-9 / FR-T8 |
+| AC-6 | BR-9 / FR-T8 |
+| AC-7 | §2 «Вне объёма» / FR-T6, TRZ §4 |
+| AC-8 | BR-4, BR-5 / FR-T2 |
+| AC-9 | NFR-2 / FR-T10 |
+| AC-10 | NFR-1, NFR-3 |
+| AC-11 | §2 «Вне объёма» (Q-1/Q-2) |
+| AC-12 | BR-10, NFR-7, NFR-8 / FR-T7, FR-T9 |

docs/work-items/ORCH-020/04-test-plan.yaml

@@ -0,0 +1,149 @@
+work_item: ORCH-020
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-17
+model_used: claude-opus-4-8
+title: "Оценка задачи, запускаемая Plane-статусом «Оценка»: триггер/возврат в Backlog/массовость/пере-оценка + прогноз {токены,время,стоимость,story points}, запись в Plane, карточка, леджер прогноз↔факт, leaf-инварианты"
+framework: pytest
+scope: >
+  Покрывается: распознавание статуса «Оценка» как триггера (handle_estimate),
+  fail-closed при отсутствии статуса, авто-возврат issue в Backlog + анти-loop,
+  анти-disruption in-flight (no-op при активном job), массовость (N вебхуков -> N оценок),
+  идемпотентная пере-оценка (UPSERT по work_item_id), расчёт прогноза из истории (usage-агрегаты),
+  маппинг величин -> story-point bucket {1,2,3,5,8} (чистая функция), never-raise/bootstrap при
+  пустой истории, запись прогноза в estimate_point и факта в point (через guard ORCH-117, fail-safe
+  при отсутствии estimate-конфига), пункт "Оценка" в Telegram-карточке, read-only блок estimator в
+  GET /queue, аддитивная таблица task_estimates (ключ work_item_id, task_id нуллабелен),
+  kill-switch + скоуп (пусто -> self-hosting only).
+  Вне покрытия: адаптивный выбор модели (Шаг 2, вне объёма), авто-уточнение модели оценки (ORCH-8),
+  автопереключение трека по сложности (ORCH-19).
+notes: >
+  Тесты используют изолированную временную SQLite-БД (фикстура init_db во временном файле) и
+  замоканные plane_sync/notifications/usage/get_project_states — без сети, без боевого Plane/Telegram,
+  без LLM. Триггер тестируется на уровне handle_issue_updated/handle_estimate с подставленными
+  proj_states (UUID статуса "Оценка"). Запись в Plane проверяется на уровне вызова write-хелперов под
+  guard (ORCH-117 autouse-floor conftest держит opt-in OFF — сетевая запись физически невозможна из
+  теста). Control-path анти-регресс: STAGE_TRANSITIONS/QG_CHECKS/check_*/machine-verdict/схемы
+  существующих таблиц не меняются; полный регресс tests/ остаётся зелёным.
+
+tests:
+  - id: TC-01
+    type: integration
+    description: "Триггер: new_state == proj_states['estimate'] -> handle_estimate вызывается; estimate-статус добавлен в _PLANE_NAME_TO_KEY как 'Оценка'->'estimate' (AC-T1)"
+    module: tests/test_orch020_estimator.py
+    expected: PASS
+
+  - id: TC-02
+    type: integration
+    description: "Fail-closed: 'estimate' отсутствует в _DEFAULT_STATES; на проекте без статуса proj_states.get('estimate') is None -> ветка инертна, handle_estimate не зовётся, нет KeyError (AC-T5)"
+    module: tests/test_orch020_estimator.py
+    expected: PASS
+
+  - id: TC-03
+    type: integration
+    description: "handle_estimate на backlog-issue (нет pipeline-задачи): прогноз вычислен, записан, затем set_issue_backlog -> issue возвращён в Backlog (AC-T1, AC-T2)"
+    module: tests/test_orch020_estimator.py
+    expected: PASS
+
+  - id: TC-04
+    type: integration
+    description: "Анти-disruption: issue с активным job (has_active_job_for_task=True) -> handle_estimate no-op + лог, оценка не запускается, статус не меняется (AC-T6)"
+    module: tests/test_orch020_estimator.py
+    expected: PASS
+
+  - id: TC-05
+    type: integration
+    description: "Анти-loop: возврат в Backlog не алиасит триггер-ветки (Backlog-UUID != estimate/stop/to_analyse/confirm_deploy/approved/rejected) -> входящий 'state->Backlog' webhook = no-op-эхо (AC-T6)"
+    module: tests/test_orch020_estimator.py
+    expected: PASS
+
+  - id: TC-06
+    type: integration
+    description: "Массовость: N issue.updated со state='Оценка' -> N независимых вызовов handle_estimate, каждый даёт прогноз; один webhook не гасит остальные (AC-T3)"
+    module: tests/test_orch020_estimator.py
+    expected: PASS
+
+  - id: TC-07
+    type: integration
+    description: "Идемпотентная пере-оценка: повторный перевод в 'Оценка' -> UPSERT по work_item_id обновляет одну строку task_estimates и estimate_point, не дублирует (AC-T4)"
+    module: tests/test_orch020_estimator.py
+    expected: PASS
+
+  - id: TC-08
+    type: unit
+    description: "estimate() возвращает {forecast_tokens,forecast_seconds,forecast_cost_usd,story_points}, story_points в {1,2,3,5,8} (AC-1)"
+    module: tests/test_orch020_estimator.py
+    expected: PASS
+
+  - id: TC-09
+    type: unit
+    description: "Маппинг величин -> story-point bucket: точная семантика 1/2/3/5/8 на граничных входах (AC-2)"
+    module: tests/test_orch020_estimator.py
+    expected: PASS
+
+  - id: TC-10
+    type: unit
+    description: "Пустая история -> bootstrap-дефолт, не исключение; estimate() never-raise при битых данных (AC-1, AC-9)"
+    module: tests/test_orch020_estimator.py
+    expected: PASS
+
+  - id: TC-11
+    type: unit
+    description: "Расчёт факта на done из usage-агрегатов (токены/время/стоимость) маппится в story-point bucket (AC-4)"
+    module: tests/test_orch020_estimator.py
+    expected: PASS
+
+  - id: TC-12
+    type: integration
+    description: "Прогноз пишется в estimate_point через set_issue_estimate_point; факт — в point через set_issue_point; поля не перепутаны, прогноз не затирается (AC-3, AC-4)"
+    module: tests/test_orch020_estimator.py
+    expected: PASS
+
+  - id: TC-13
+    type: integration
+    description: "Telegram-карточка содержит пункт 'Оценка' (время/токены/стоимость); пустой прогноз -> пункт опускается, карточка не падает (AC-5)"
+    module: tests/test_orch020_estimator.py
+    expected: PASS
+
+  - id: TC-14
+    type: integration
+    description: "Plane-коммент с прогнозом постится через add_comment (best-effort) (AC-6)"
+    module: tests/test_orch020_estimator.py
+    expected: PASS
+
+  - id: TC-15
+    type: unit
+    description: "kill-switch estimator_enabled=false -> модуль инертен (handle_estimate no-op, нет записей в Plane/карточку/таблицу); applies() локален и first (AC-9)"
+    module: tests/test_orch020_estimator.py
+    expected: PASS
+
+  - id: TC-16
+    type: unit
+    description: "Скоуп estimator_repos пуст -> активен только self-hosting orchestrator; enduro-trails -> no-op (AC-9)"
+    module: tests/test_orch020_estimator.py
+    expected: PASS
+
+  - id: TC-17
+    type: integration
+    description: "GET /queue содержит read-only блок estimator (флаг/скоуп/счётчики прогнозов/записей/возвратов); existing-поля не меняются (AC-9)"
+    module: tests/test_orch020_estimator.py
+    expected: PASS
+
+  - id: TC-18
+    type: unit
+    description: "Аддитивная таблица task_estimates: CREATE TABLE IF NOT EXISTS идемпотентна; record_estimate/set_actual/get_estimate хранят прогноз+факт+дельту с ключом work_item_id (task_id нуллабелен); существующие таблицы не изменены (AC-12)"
+    module: tests/test_orch020_estimator.py
+    expected: PASS
+
+  - id: TC-19
+    type: integration
+    description: "fail-safe записи в Plane: estimate-система не настроена -> set_issue_estimate_point/point best-effort пропуск + лог, без падения; авто-возврат в Backlog всё равно отрабатывает (AC-12, AC-T2, NFR-7)"
+    module: tests/test_orch020_estimator.py
+    expected: PASS
+
+  - id: TC-20
+    type: unit
+    description: "Анти-регресс control-path: STAGE_TRANSITIONS/QG_CHECKS/check_*/machine-verdict-ключи, resolve_agent_model/resolve_agent_effort не изменены; статус 'Оценка' не добавлен как ребро стадий (AC-10, AC-11)"
+    module: tests/test_orch020_estimator.py
+    expected: PASS

docs/work-items/ORCH-020/06-adr/ADR-001-task-estimation-status-trigger.md

@@ -0,0 +1,262 @@
+---
+work_item: ORCH-020
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-17
+model_used: claude-opus-4-8
+---
+
+# ADR-001: Оценка задачи как side-механизм, запускаемый операторским Plane-статусом «Оценка», с детерминированной эвристикой по истории
+
+Work Item: **ORCH-020** — Оценка задачи (прогноз стоимости/времени/токенов/story points), запускаемая статусом «Оценка»
+Стадия: **architecture**
+Сквозная регистрация: **`docs/architecture/adr/adr-0054-task-estimation-status-trigger.md`** (решение кросс-каттинговое: новый член семейства операторских action-статусов + новая аддитивная таблица + новый primitive записи в Plane + новый leaf).
+
+## Статус
+Proposed
+
+## Контекст
+
+BRD/TRZ (`01-brd.md`/`02-trz.md`, ревизия после REJECT 2026-06-17) требуют: оператор **массово**
+переводит backlog-задачи в выделенный Plane-статус **«Оценка»**, по каждой оркестратор прогнозирует
+**стоимость / время / токены / сложность (story points `{1,2,3,5,8}`)**, пишет прогноз в Plane-поле
+`estimate_point`, публикует в Plane-комменте и пункте «Оценка» Telegram-карточки, сохраняет в леджер
+прогноз↔факт и **возвращает issue в Backlog**; пере-оценка повтором идемпотентна; по завершении задачи
+факт пишется в `point`. Шаг 2 (адаптивный выбор модели) — **вне объёма** (заказчик: «Модели не выбираем
+и не меняем»).
+
+Факты, сверенные с кодом (не изобретать):
+- **Семейство операторских action-статусов уже существует.** `webhooks/plane.py::handle_issue_updated`
+  (строки 163–181) разбирает STOP (ORCH-090) и Confirm Deploy (ORCH-059) через `proj_states.get("<key>")`;
+  оба **намеренно отсутствуют** в `plane_sync._DEFAULT_STATES` (fail-closed) и сопоставляются именем через
+  `_PLANE_NAME_TO_KEY` (`src/plane_sync.py:131`). Статус «Оценка» — третий представитель того же семейства.
+- **Массовость «бесплатна»:** Plane multi-select → N независимых `issue.updated`-вебхуков; спец-batch-кода не нужно.
+- **Фактура для калибровки накоплена:** `usage.task_usage_summary(task_id)` (`src/usage.py:834`) агрегирует
+  токены/стоимость per-task из `agent_runs`; тайминги — `tasks.created_at/updated_at`,
+  `agent_runs.started_at/finished_at`. Колонка `tasks.track` (ORCH-019) различает `full`/`bug`.
+- **Запись в Plane идёт через guard ORCH-117:** все три примитива записи (`update_issue_state`/`add_comment`/
+  `_set_issue_state_direct`) проходят `_guard_allows_write` (`src/plane_sync.py:847`) — из тест/worktree-процесса
+  запись в боевой проект физически заблокирована.
+- **estimate-система Plane не настроена** на момент анализа; `estimate_point` — FK на estimate-point estimate-системы,
+  `point` — целочисленное поле issue. В `src/` **нет** кода работы с Plane-estimate (net-new интеграция).
+- **leaf-паттерн платформы** (`serial_gate`/`coverage_gate`/`bug_fast_track`/`lessons`): never-raise, kill-switch
+  `*_enabled`, скоуп `*_repos` (пусто → self-hosting only через `qg.checks.is_self_hosting_repo`), read-only блок
+  в `GET /queue`, `applies(repo)` локально и ПЕРВЫМ.
+- **Хук done-факта:** блок `if next_stage == "done"` в `stage_engine.advance_stage` (`src/stage_engine.py:521`)
+  — единственная авторитетная точка перехода в терминал.
+
+**Инвариант (NFR-1/NFR-3):** оценка — наблюдатель/продюсер, **не** Quality Gate и **не** переход стадии.
+`STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict-ключи / схемы существующих таблиц —
+байт-в-байт. Горячий путь `resolve_agent_model`/`resolve_agent_effort`/`_spawn` — не трогается.
+
+## Решение
+
+### Сводка
+Вводим **новый операторский Plane-статус «Оценка»** как третий член семейства action-статусов
+(STOP/Confirm Deploy) — fail-closed `.get("estimate")`-ветка в `handle_issue_updated`, делегирующая
+**новому leaf-модулю `src/estimator.py`** (never-raise, kill-switch, скоуп). Механизм прогноза —
+**детерминированная эвристика по истории завершённых задач** (чистые функции, **без LLM-вызова**):
+прогноз = средние токены/время/стоимость похожих `done`-задач того же репо/трека, story-points —
+чистая функция-бакетизатор. Прогноз пишется в Plane (`estimate_point` + коммент), Telegram-карточку и
+**новую аддитивную таблицу `task_estimates`** (UPSERT по `work_item_id`); затем issue возвращается в
+`Backlog`. По завершении задачи факт (из `usage.py`) пишется в `point` и в леджер. Всё — аддитивно,
+под флагами, fail-safe, без касания control-path.
+
+### D1 — Механизм прогноза: детерминированная эвристика по истории, **без LLM** (NFR-4, NFR-5; решение Q открытого вопроса TRZ §NFR-4)
+Это **главное архитектурное решение**, которое TRZ явно делегировал архитектору.
+
+- **Выбор: чистая детерминированная эвристика** (in-process, без сетевого LLM-вызова и без субпроцесса).
+  Прогноз вычисляется парой индексированных SQL-чтений + чистыми функциями за микросекунды.
+- **Почему не LLM-оценщик / не гибрид (на этом шаге):**
+  1. **NFR-5 (массовость).** Multi-select десятков задач → десятки почти одновременных вебхуков. LLM-вызов
+     на оценку умножился бы на N и конкурировал бы за **единственный транспорт LLM** (`launcher._spawn`) с
+     боевыми агентами, рискуя замедлить обслуживание **других** проектов (enduro) из общего прода.
+  2. **NFR-4 (стоимость ≪ ценности).** Opus-вызов на каждую из десятков backlog-задач — это реальные $ за
+     саму оценку; эвристика бесплатна.
+  3. **Политика ORCH-118 (determinization-roadmap).** Платформа целенаправленно **сокращает** avoidable
+     LLM-пути (`llm-usage-policy.md`: «LLM — только где нужно настоящее суждение»). Оценка размера по истории
+     — деривируемая из tool-сигналов величина, **не** требующая суждения LLM. Вводить здесь новый LLM-путь
+     прямо противоречит действующей политике.
+  4. **Воспроизводимость/тестируемость.** Детерминированный бакетизатор покрывается unit-тестами на границах
+     (AC-2 / TC-09), чего LLM не даёт.
+- **Стек-расширяемость (BR-6 содержания, без реализации сейчас):** контракт `estimator.estimate(work_item_id,
+  description|issue, repo) -> {forecast_tokens, forecast_seconds, forecast_cost_usd, story_points}` —
+  **граница расширения**. Будущий гибридный LLM-рефайнер (если когда-нибудь понадобится) встраивается
+  ЗА этой границей без изменения вызывающих. Сейчас LLM-рефайнер **не строится** (Шаг 2 / выбор модели вне
+  объёма, AC-11).
+
+### D2 — Модель прогноза: средние по «похожим» завершённым задачам + bootstrap (BR-1, BR-2)
+- **«Похожие» = тот же `repo` И тот же `track`** (`full`/`bug`, ORCH-019) среди задач со `stage='done'`.
+  Трек — дешёвый, уже хранимый, осмысленный разрез сложности (багфикс короче полного цикла).
+- **Источник фактуры (read-only):** тонкий агрегат `db.completed_task_stats(repo, track) ->
+  {n, mean_tokens, mean_cost_usd, mean_seconds}` поверх `agent_runs` (токены/стоимость, как
+  `task_usage_summary`, но сгруппировано по завершённым задачам) и `tasks` (время = `updated_at - created_at`,
+  отсечка аномалий по `estimator_wall_cap_s`, зеркало `tracker_brd_review_cap_s` ORCH-087). `usage.py`
+  переиспользуется read-only.
+- **Прогноз = средние** по выборке. `forecast_tokens = mean_tokens`, `forecast_cost_usd = mean_cost_usd`,
+  `forecast_seconds = mean_seconds`.
+- **Bootstrap (пустая/малая история):** `n < estimator_min_samples` (дефолт 3) → значения берутся из
+  конфиг-дефолтов `estimator_bootstrap_{tokens,cost_usd,seconds}` (или смешиваются с имеющейся выборкой —
+  деталь реализации; разработчику разрешена линейная интерполяция). **Никогда не исключение** (AC-1/TC-10).
+- **Сигналы описания (опц., v1 — не обязательны):** длина текста постановки / наличие метки `Bug` могут
+  скорректировать выбор трека; в v1 достаточно `repo+track`. Расширение — за границей D1.
+
+### D3 — Бакетизатор story points: чистая функция, конфигурируемые пороги (BR-3, AC-2)
+- **Чистая функция** `estimator.story_points_for(forecast) -> int ∈ {1,2,3,5,8}`. Первичный сигнал —
+  **`forecast_cost_usd`** (прямая ось «сколько будет стоить», запрошенная заказчиком; легко
+  ре-калибруется конфигом при смене тарифа/провайдера ORCH-13).
+- **Пороги** — конфиг `estimator_sp_cost_thresholds` (CSV из 4 возрастающих кат-оффов `t1,t2,t3,t5`),
+  семантика `<=` по возрастанию:
+  `cost ≤ t1 → 1` · `≤ t2 → 2` · `≤ t3 → 3` · `≤ t5 → 5` · `иначе → 8`.
+  **Дефолты (bootstrap, подлежат калибровке):** `0.50, 2.00, 5.00, 12.00` ($).
+- **Семантика шкалы (фиксирована, BR-3/FR-T4):** `1` docs/label/config · `2` небольшой фикс · `3` средняя ·
+  `5` сложная (код+тесты) · `8` эпик/разбивать. Значения вне `{1,2,3,5,8}` не выдаются.
+- **Факт-story-points** считаются той же функцией по фактической стоимости (консистентность прогноз↔факт).
+- Калибровка порогов — задача петли ORCH-8 поверх леджера D7; пороги конфигурируемы именно ради этого.
+
+### D4 — Триггер: fail-closed ветка `estimate`, взаимоисключение жестов (BR-T1, BR-T5, AC-T1, AC-T5)
+- `plane_sync._PLANE_NAME_TO_KEY["Оценка"] = "estimate"`; ключ `estimate` **НЕ добавляется** в
+  `_DEFAULT_STATES` (fail-closed, как `stop`/`confirm_deploy`). На доске без статуса
+  `proj_states.get("estimate") is None` → ветка инертна (нет KeyError, нет оценки).
+- В `handle_issue_updated` — отдельная ветка `estimate_state = proj_states.get("estimate")`;
+  `if estimate_state and new_state == estimate_state: await handle_estimate(...)`. **Размещение:** сразу
+  после ветки `stop` (раннее, рядом с прочими `.get`-action-статусами). Корректность взаимоисключения
+  обеспечена **различием UUID** статусов (а не порядком); порядок выбран для читаемости. Ветка не
+  алиасит STOP/`to_analyse`/`confirm_deploy`/`approved`/`rejected`.
+
+### D5 — `handle_estimate`: анти-disruption, авто-возврат, анти-loop (BR-T2, BR-T6, FR-T2, FR-T5, AC-T2, AC-T6)
+- `handle_estimate(data, project_id)` резолвит `plane_id`/`work_item_id`; `repo` — по проекту
+  (`projects.get_project_by_repo`/реестр). **Исполнение off-loop** через `asyncio.to_thread` (зеркало
+  `handle_stop`), т.к. ядро синхронно и делает сетевые Plane-вызовы. Контракт never-raise.
+- **Guard-цепочка (каждый — no-op-with-log при невыполнении):**
+  1. `estimator.applies(repo)` — kill-switch + скоуп, локально и ПЕРВЫМ (без сети при выключенном флаге);
+  2. **анти-disruption (BR-T6):** issue с pipeline-задачей, у которой есть **активный** job
+     (`db.has_active_job_for_task(task_id)`, `src/db.py:1323`) → no-op + лог (не выдёргивать in-flight
+     работу). Backlog-issue (нет задачи) или терминальная/idle-задача → оценка допустима.
+- Далее: `estimator.estimate(...)` → запись прогноза (D6/D7/D8) → **`set_issue_backlog(work_item)`** (D6).
+- **Анти-loop:** `backlog` не совпадает ни с одной триггер-веткой → входящий «state→Backlog» webhook —
+  no-op-эхо. Возврат best-effort: сбой записи статуса не роняет флоу (прогноз уже записан).
+
+### D6 — Запись в Plane: `estimate_point` (FK) + `point` (int) + коммент + Backlog (BR-7, BR-8, FR-T7, NFR-6, NFR-7)
+Новые write-хелперы в `plane_sync.py`, все через `_guard_allows_write` (ORCH-117), все never-raise:
+- **`set_issue_backlog(work_item)`** — `get_project_states(pid)["backlog"]` → `_set_issue_state_direct`
+  (ключ `backlog` уже в `_DEFAULT_STATES`). Зеркало `set_issue_done`/`set_issue_in_review`.
+- **`set_issue_point(work_item, value:int)`** — PATCH `{"point": int(value)}` (легаси целочисленное поле,
+  устойчиво — не зависит от estimate-системы). Это запись **факта** (BR-8).
+- **`set_issue_estimate_point(work_item, value)`** — резолв estimate-point UUID через новый
+  `get_project_estimate_points(project_id)` (GET project → `estimate` id → GET estimate-points → map
+  `value→uuid`, TTL-кэш по образцу `get_project_states`/ORCH-068), затем PATCH `{"estimate_point": <uuid>}`.
+  Это запись **прогноза** (BR-7).
+- **fail-safe (NFR-7):** estimate-система не настроена / значение вне системы / поле отсутствует / 4xx →
+  **best-effort пропуск + лог**, не падение. `point` устойчивее `estimate_point` (сырой int), но оба
+  best-effort.
+- **Коммент** — `add_comment` с прогнозом (стоимость/время/токены/story points), `author="stream"`.
+- Прогноз пишется в `estimate_point`, факт — в `point`; поля **не перепутаны**; факт **не перезаписывает**
+  `estimate_point` (AC-3/AC-4).
+
+### D7 — Персистентность: аддитивная `task_estimates`, UPSERT по `work_item_id` (BR-10, FR-T9, NFR-8, AC-T4, AC-12)
+- **Новая аддитивная таблица** `task_estimates` (`CREATE TABLE IF NOT EXISTS` в `init_db()`, паттерн
+  `coverage_baseline`/`lessons`/`transition_lease`), **`UNIQUE(work_item_id)`** для идемпотентного UPSERT.
+  Полная схема, типы, индексы — `08-data-requirements.md`.
+- Хелперы `db.record_estimate(**)` (UPSERT прогноза по `work_item_id`), `db.set_actual(work_item_id, ...)`
+  (запись факта+дельты), `db.get_estimate(work_item_id)`, `db.estimates_snapshot()`.
+- Ключ — `work_item_id` (на момент оценки `task_id` может быть `NULL` — issue на бэклоге, строки `tasks`
+  ещё нет). `task_id` заполняется позже, когда оценённый issue входит в пайплайн (best-effort).
+- Существующие таблицы — **не изменяются** (NFR-8).
+
+### D8 — Поверхности отображения: Plane-коммент + пункт «Оценка» в Telegram-карточке (BR-9, FR-T8, AC-5, AC-6)
+- **Plane-коммент** — D6.
+- **Telegram-карточка** — пункт **«Оценка»** (время · токены · стоимость) в рендере общей карточки
+  (`notifications.update_task_tracker`), читается из `task_estimates` по `work_item_id`; never-raise; пустой
+  прогноз → пункт опускается; инвариант «одна карточка на задачу» (ORCH-087) не нарушается;
+  HTML-data-слоты экранируются `html.escape` ровно один раз (канон ORCH-095).
+- **Замечание о времени появления строки:** карточка существует у pipeline-задачи; если оценка сделана на
+  бэклоге до старта пайплайна — строка «Оценка» появится при первом рендере карточки после старта
+  (`task_estimates` хранится по `work_item_id`, переживает старт). Приемлемо и задокументировано.
+
+### D9 — Запись факта на `done` (BR-8, FR-T7, AC-4)
+- Тонкая **best-effort врезка** `estimator.record_actual_on_done(task_id, repo, work_item_id)` в
+  `stage_engine.advance_stage` в существующем блоке `if next_stage == "done"` (`src/stage_engine.py:521`),
+  ПОСЛЕ terminal-sync, в своём `try/except` (never-raise; зеркало release-merge-lease-врезки рядом).
+- Считает факт из `usage.task_usage_summary(task_id)` + тайминги → `story_points_for(actual)` →
+  `db.set_actual(...)` + `set_issue_point(work_item, actual_sp)`. **Не** перезаписывает `estimate_point`.
+- `STAGE_TRANSITIONS`/гейт `check_deploy_status`/machine-verdict — не трогаются (врезка после решения о
+  переходе, не влияет на него).
+
+### D10 — Толерантность к массовости (NFR-5, AC-T3)
+- **Сглаживание встроено в выбор D1:** детерминированная эвристика без LLM/субпроцесса → per-issue ядро
+  O(1) (пара индексированных чтений). Доминирующая стоимость — несколько ограниченных Plane HTTP-раундов на
+  issue, исполняемых off-loop (`to_thread`).
+- **Новой очереди НЕ вводим:** очередь `jobs`/`max_concurrency` — для агентов (control-path); оценка не
+  занимает её слот (NFR-3). Опциональный простой in-process семафор `estimator_max_inflight` (дефолт
+  «щедрый», эффективно off) — конфиг-семя на случай измеренной перегрузки; в v1 не активничает.
+- Один webhook не гасит остальные (N независимых вызовов).
+
+### D11 — leaf-инварианты, флаги, наблюдаемость (NFR-2, NFR-3, FR-T10, AC-9)
+- **Leaf `src/estimator.py`** (never-raise, паттерн `bug_fast_track`/`coverage_gate`): импортирует только
+  `config` (+ лениво `db`/`usage`/`plane_sync`/`notifications`/`qg.checks`), не импортирует `stage_engine`/
+  `launcher`. Публичные: `applies(repo)`, `estimate(...)`, `story_points_for(...)`,
+  `record_actual_on_done(...)`, `snapshot()`.
+- **Флаги** (`config.py`, дефолты безопасные): `estimator_enabled` (kill-switch, env
+  `ORCH_ESTIMATOR_ENABLED`), `estimator_repos` (CSV, env `ORCH_ESTIMATOR_REPOS`; **пусто → self-hosting
+  only**), + тюнинг `estimator_min_samples`, `estimator_bootstrap_tokens/cost_usd/seconds`,
+  `estimator_sp_cost_thresholds`, `estimator_wall_cap_s`, `estimator_max_inflight`.
+- `applies(repo)` локально и ПЕРВЫМ → выключенный флаг = нулевой сетевой оверхед, нулевая регрессия для
+  enduro/orchestrator.
+- **Наблюдаемость:** read-only блок `estimator` в `GET /queue` (флаг/скоуп + счётчики прогнозов/записей в
+  Plane/возвратов-в-Backlog/фактов); при невозможности записи в Plane — лог-warning.
+
+### D12 — Опциональные программные эндпоинты (TRZ §4, AC-7)
+- `POST /estimate?work_item=<id>`, `POST /estimate/backlog`, `GET /estimate?work_item=<id>` — **то же ядро**
+  `estimator.estimate(...)`, идемпотентны. Удобство/диагностика, **не** основной триггер. Их отсутствие не
+  нарушает приёмку. Не преподносить как единственный способ запуска.
+
+## Альтернативы
+- **LLM-оценщик (отдельный вызов на задачу) / гибрид** — отвергнуто на этом шаге: нарушает NFR-4
+  (стоимость самой оценки), NFR-5 (массовость конкурирует за единственный LLM-транспорт), и политику
+  ORCH-118 (avoidable LLM control/consultation path). Граница `estimate()` оставляет место под будущий
+  гибрид без переписывания вызывающих.
+- **Авто-оценка каждой задачи на `start_pipeline`** — отвергнуто: это модель, которую заказчик **явно
+  отклонил** (REJECT 2026-06-17). Оценка — операторский on-demand жест.
+- **Новый массовый `POST /estimate-batch` как основной путь** — отвергнуто: массовость даёт сам Plane
+  multi-select (N вебхуков); batch-эндпоинт — лишний код и второй источник истины.
+- **Отдельная стадия/ребро `STAGE_TRANSITIONS` для оценки** — отвергнуто: нарушает NFR-1; оценка не есть
+  переход стадии. Side-механизм по образцу STOP/Confirm Deploy.
+- **Бакетизация по токенам вместо стоимости** — рассмотрено: токены модель-независимы, но заказчик мыслит
+  осью «сколько стоит». Выбрана стоимость с конфигурируемыми порогами (ре-калибруемыми при ORCH-13);
+  переключение сигнала — локальная правка за чистой функцией.
+- **Хранение оценки в `tasks` колонками** — отвергнуто: на момент оценки строки `tasks` может не быть
+  (бэклог); ключ по `work_item_id` в отдельной таблице корректнее (NFR-8, аддитивность).
+
+## Последствия
+- **+** Оператор видит прогноз (стоимость/время/токены/story points) до отправки задачи в работу; массовая
+  оценка одним multi-select; пере-оценка идемпотентна; фундамент петли калибровки (ORCH-8) заложен (леджер).
+- **+** Нулевая нагрузка на LLM-транспорт и нулевая $-стоимость самой оценки; bulk-безопасно; полностью
+  детерминировано и тестируемо; согласовано с determinization-политикой ORCH-118.
+- **+** Control-path/гейты/горячий путь не тронуты; enduro и текущий orchestrator при выключенном флаге /
+  на доске без статуса — нулевая регрессия.
+- **−** Точность прогноза на холодном старте ограничена (мало истории) → митигейшн: bootstrap-дефолты +
+  петля калибровки порогов поверх леджера (BR-10). Пороги story-points — начальные, подлежат калибровке.
+- **−** Net-new интеграция с Plane-estimate API (`estimate_point` — FK) добавляет инфра-предусловие
+  (estimate-система с Fibonacci) и хрупкость записи → митигейшн: best-effort/fail-safe (NFR-7), устойчивый
+  `point` (raw int) для факта, точная спека — `07-infra-requirements.md`.
+- **− (масштаб)** Это **аддитивный leaf по устоявшемуся паттерну** (как serial_gate/coverage_gate/lessons),
+  без новой стадии, без правки существующих таблиц, без смены БД-движка. **`arch:major-change` не требуется.**
+- **Откат:** `ORCH_ESTIMATOR_ENABLED=false` → весь модуль инертен (статус «Оценка» не обрабатывается, нет
+  записей в Plane/карточку/таблицу; конвейер байт-в-байт до ORCH-020). Доп. откат «на уровне доски» — не
+  создавать статус «Оценка» (fail-closed). Таблица `task_estimates` остаётся (аддитивна, безвредна).
+
+## Ссылки
+- BRD: `docs/work-items/ORCH-020/01-brd.md`
+- TRZ: `docs/work-items/ORCH-020/02-trz.md`
+- Acceptance: `docs/work-items/ORCH-020/03-acceptance-criteria.md`
+- Сквозной ADR: `docs/architecture/adr/adr-0054-task-estimation-status-trigger.md`
+- Инфра/данные/риски: `07-infra-requirements.md`, `08-data-requirements.md`, `10-tech-risks.md`
+- Сверено по коду: `src/plane_sync.py` (`_PLANE_NAME_TO_KEY`/`_DEFAULT_STATES`/`_guard_allows_write`/write-хелперы),
+  `src/webhooks/plane.py` (`handle_issue_updated`/`handle_stop`), `src/usage.py:834` (`task_usage_summary`),
+  `src/db.py` (`has_active_job_for_task`/`_ensure_column`/leaf-DDL-паттерн), `src/stage_engine.py:521`
+  (`next_stage=="done"`), `src/bug_fast_track.py` (`applies`/label-аппарат), `src/qg/checks.py`
+  (`is_self_hosting_repo`)
+- Прецеденты: ORCH-090 (STOP), ORCH-059 (Confirm Deploy), ORCH-117 (write-guard), ORCH-019 (`track`),
+  ORCH-118 (LLM-политика), ORCH-098 (leaf-таблица), ORCH-087/095 (Telegram-карточка)

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

@@ -0,0 +1,76 @@
+---
+work_item: ORCH-020
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-17
+model_used: 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`).

docs/work-items/ORCH-020/08-data-requirements.md

@@ -0,0 +1,85 @@
+---
+work_item: ORCH-020
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-17
+model_used: claude-opus-4-8
+---
+
+# 08 — Требования к данным: ORCH-020 — Оценка задачи, запускаемая статусом «Оценка»
+
+Work Item: **ORCH-020** · Repo: **orchestrator** · Стадия: architecture
+
+> When-applicable / информационный (гейтом не парсится). Одна **новая аддитивная** таблица; существующие
+> таблицы (`tasks`/`agent_runs`/`jobs`/…) — **не изменяются** (NFR-8).
+
+## Изменения схемы БД
+
+**Новая аддитивная таблица `task_estimates`** (`CREATE TABLE IF NOT EXISTS` в `db.init_db()`, паттерн
+`coverage_baseline`/`lessons`/`transition_lease`; идемпотентно, restart-safe на общей прод-БД):
+
+```sql
+CREATE TABLE IF NOT EXISTS task_estimates (
+    id                    INTEGER PRIMARY KEY AUTOINCREMENT,
+    work_item_id          TEXT NOT NULL UNIQUE,   -- ключ/UPSERT-цель (issue может не иметь task на момент оценки)
+    task_id               INTEGER,                -- FK tasks.id; НУЛЛАБЕЛЕН до старта пайплайна
+    repo                  TEXT,
+    -- Прогноз (на момент перевода в «Оценка»):
+    forecast_tokens       INTEGER,
+    forecast_seconds      INTEGER,
+    forecast_cost_usd     REAL,
+    forecast_story_points INTEGER,                -- из {1,2,3,5,8}
+    -- Факт (на момент перехода задачи в `done`):
+    actual_tokens         INTEGER,
+    actual_seconds        INTEGER,
+    actual_cost_usd       REAL,
+    actual_story_points   INTEGER,                -- из {1,2,3,5,8}
+    -- Метаданные:
+    source                TEXT,                   -- 'status' | 'manual' | 'api'
+    estimate_count        INTEGER NOT NULL DEFAULT 1,  -- число пере-оценок (инкремент при UPSERT)
+    created_at            TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at            TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_task_estimates_repo    ON task_estimates (repo);
+CREATE INDEX IF NOT EXISTS idx_task_estimates_task_id ON task_estimates (task_id);
+```
+
+- **`UNIQUE(work_item_id)`** — несущий инвариант идемпотентной пере-оценки (BR-T4/AC-T4): повторный перевод
+  в «Оценка» делает **UPSERT** (`INSERT … ON CONFLICT(work_item_id) DO UPDATE …`), обновляя одну строку и
+  инкрементируя `estimate_count`; дублей строк нет.
+- **Дельта** прогноз↔факт **не хранится отдельной колонкой** — вычисляется на чтение из forecast/actual
+  (избегаем рассинхрона; калибровке достаточно обеих величин). При желании реализатор может добавить
+  материализованные `delta_*` — не обязательно (BR-10 требует «обе величины + дельту»; вычисляемая дельта
+  это удовлетворяет).
+- **Индексы:** по `repo` (выборка/снапшот по проекту) и `task_id` (связь с задачей). По `work_item_id`
+  индекс создаётся автоматически (UNIQUE).
+
+## Новые/изменённые сущности
+
+- **Хелперы `db.py`** (каждый открывает/закрывает свою connection, паттерн `coverage_baseline`/`lessons`;
+  leaf `estimator`/вызывающие оборачивают в never-raise):
+  - `record_estimate(work_item_id, repo, task_id=None, forecast_*=…, source='status') -> int` — UPSERT
+    прогноза по `work_item_id`; инкремент `estimate_count`, стамп `updated_at`.
+  - `set_actual(work_item_id, actual_tokens, actual_seconds, actual_cost_usd, actual_story_points,
+    task_id=None) -> bool` — запись факта; **не трогает** forecast-поля.
+  - `get_estimate(work_item_id) -> dict | None` — текущая строка прогноз/факт.
+  - `estimates_snapshot(limit=…) -> dict` — read-only для блока `estimator` в `GET /queue`.
+- **Read-only агрегат истории** `db.completed_task_stats(repo, track) -> {n, mean_tokens, mean_cost_usd,
+  mean_seconds}` — поверх `agent_runs` (токены/стоимость, как `task_usage_summary`) и `tasks`
+  (`stage='done'`, время = `updated_at − created_at` с отсечкой `estimator_wall_cap_s`). **Только чтение**
+  существующих таблиц; новых колонок не вводит.
+
+## Совместимость данных / миграции
+
+- **Аддитивность (NFR-8):** только новая таблица + новые read/write-хелперы; **ни одной** правки
+  существующих таблиц/колонок/индексов. `STAGE_TRANSITIONS`/`QG_CHECKS`/machine-verdict-ключи независимы
+  от данных оценки.
+- **Идемпотентность миграции:** `CREATE TABLE IF NOT EXISTS` + `CREATE INDEX IF NOT EXISTS` — no-op на уже
+  созданной таблице; безопасно на живой общей прод-БД (enduro не затронут — таблица общая, но писать в неё
+  будет только self-hosting-скоуп; строки enduro не появляются, пока репо вне `estimator_repos`).
+- **Restart-safe:** строки `task_estimates` переживают рестарт; прогноз, сделанный на бэклоге (с
+  `task_id=NULL`), сохраняется до старта пайплайна и связывается с `task_id` позже (best-effort).
+- **Влияние на общую прод-БД:** таблица малая (одна строка на оценённый issue), индексы лёгкие; нагрузка на
+  hot-path **нулевая** (claim/queue не читают `task_estimates`). Откат (`ORCH_ESTIMATOR_ENABLED=false`)
+  оставляет таблицу пустой/неиспользуемой — безвредно.

docs/work-items/ORCH-020/10-tech-risks.md

@@ -0,0 +1,47 @@
+---
+work_item: ORCH-020
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-17
+model_used: claude-opus-4-8
+---
+
+# 10 — Технические риски: ORCH-020 — Оценка задачи, запускаемая статусом «Оценка»
+
+Work Item: **ORCH-020** · Repo: **orchestrator** · Стадия: architecture
+
+> Информационный (гейтом не парсится). Риски реализации и их митигейшн.
+
+## Реестр рисков
+
+| ID | Риск | Вер. | Влия. | Митигейшн |
+|----|------|------|-------|-----------|
+| TR-1 | **Массовый перевод (десятки issue → десятки вебхуков) перегружает прод**, тормозя обслуживание enduro | Сред. | Выс. | D1: детерминированная эвристика **без LLM/субпроцесса** (ядро O(1)); off-loop `to_thread`; **не** занимает слот `jobs/max_concurrency`; опц. семафор `estimator_max_inflight` как семя; никакого LLM-fan-out за единственный транспорт |
+| TR-2 | **Статус «Оценка» выдёргивает in-flight задачу** в Backlog / прерывает работу | Низ. | Выс. | D5: guard `has_active_job_for_task` → no-op при активном job; авто-возврат только в `Backlog`, никогда не трогает `STAGE_TRANSITIONS`/стадии |
+| TR-3 | **Цикл вебхуков** (возврат в Backlog → новый webhook → повторная оценка) | Низ. | Сред. | D4/D5: `backlog` не совпадает ни с одной триггер-веткой → входящий «state→Backlog» = no-op-эхо (анти-loop по построению) |
+| TR-4 | **estimate-система Plane не настроена / `estimate_point` — FK** → запись прогноза падает/невозможна | Сред. | Сред. | D6/NFR-7: best-effort пропуск + лог, never-raise; факт пишется в устойчивый int-`point`; точная спека и предусловие — `07-infra-requirements.md` (P-2) |
+| TR-5 | **Запись в боевой Plane из теста/worktree** (общая доска) | Низ. | Выс. | D6: все три записи (`estimate_point`/`point`/коммент/состояние) под `_guard_allows_write` (ORCH-117) → из pytest-процесса физически заблокированы |
+| TR-6 | **Неточность прогноза на холодном старте** (мало истории) подрывает доверие | Выс. | Низ. | D2: bootstrap-дефолты ниже `estimator_min_samples`; леджер `task_estimates` (D7) + конфигурируемые пороги D3 как фундамент петли калибровки (ORCH-8) |
+| TR-7 | **Пороги story-points произвольны** (нет калиброванных данных day-1) | Сред. | Низ. | D3: пороги вынесены в конфиг `estimator_sp_cost_thresholds`; дефолты помечены как bootstrap; ре-калибровка поверх леджера без правки кода |
+| TR-8 | **Расползание в Шаг 2** (per-task override модели/эффорта = касание control-path) | Низ. | Выс. | NFR-1/NFR-3/AC-11: жёсткий out-of-scope; горячий путь `resolve_agent_model`/`resolve_agent_effort`/`_spawn` не трогается; follow-up на отдельный work item (зависимость ORCH-13) |
+| TR-9 | **Идемпотентность пере-оценки нарушена** (дубли строк) | Низ. | Сред. | D7: `UNIQUE(work_item_id)` + UPSERT; покрыто TC-07 |
+| TR-10 | **Дрейф канона онбординга** (23-й статус «Оценка» не учтён) | Низ. | Низ. | D4 + `07` I-3: имя статуса берётся из `_PLANE_NAME_TO_KEY` (онбординг-проверка ловит автоматически); группа фиксирована каноном; estimate-система — `manual-step` |
+| TR-11 | **Строка «Оценка» в Telegram-карточке роняет рендер** | Низ. | Сред. | D8: never-raise; пустой прогноз → пункт опускается; `html.escape` один раз (ORCH-095); инвариант «одна карточка» (ORCH-087) не нарушается |
+| TR-12 | **Врезка факта на `done` влияет на переход** | Низ. | Выс. | D9: best-effort `try/except` ПОСЛЕ решения о переходе; `check_deploy_status`/`STAGE_TRANSITIONS`/machine-verdict не трогаются |
+
+## Сводный вывод
+
+Доминирующий класс рисков — **операционные** (массовость TR-1, инфра-предусловия Plane TR-4/TR-10) и
+**точностные** (TR-6/TR-7), а **не** архитектурно-структурные: control-path, гейты, горячий путь запуска
+агентов и схемы существующих таблиц **не затрагиваются** (NFR-1/NFR-3), всё аддитивно, под kill-switch,
+never-raise, fail-safe, скоуп self-hosting.
+
+Выбор детерминированной эвристики (D1) **снимает корневой риск масштаба** (TR-1) и согласован с
+determinization-политикой ORCH-118 — это сознательно консервативное, обратимое решение.
+
+**Эскалация `arch:major-change` не требуется:** изменение — аддитивный leaf по устоявшемуся паттерну
+(serial_gate/coverage_gate/lessons/cancel), без новой стадии, без правки существующих таблиц, без смены
+БД-движка. **Возврат в анализ не требуется:** ТЗ реализуемо без нарушения принципов архитектуры.
+Остаточный риск для прод-конвейера (self-hosting) — **низкий**; точность прогноза — итеративно улучшаемая
+через заложенный леджер калибровки.

docs/work-items/ORCH-020/12-review.md

@@ -0,0 +1,95 @@
+---
+verdict: REQUEST_CHANGES
+work_item: ORCH-020
+stage: review
+author_agent: reviewer
+status: changes-requested
+created_at: 2026-06-17
+model_used: claude-opus-4-8
+type: review
+work_item_id: ORCH-020
+version: 1
+---
+
+# Review ORCH-020 — Оценка задачи, запускаемая Plane-статусом «Оценка»
+
+## Summary
+
+Реализация **технически сильная**: новый leaf `src/estimator.py` (never-raise, kill-switch +
+скоуп), детерминированная эвристика без LLM (как требует ADR-001 D1 и политика ORCH-118), точечные
+аддитивные врезки в `webhooks/plane.py` / `plane_sync.py` / `stage_engine.py` / `db.py` /
+`notifications.py` / `main.py` / `config.py`. Все 12+ критериев приёмки (AC-T1…AC-12) покрыты тестами
+`tests/test_orch020_estimator.py` (TC-01…TC-20) — **21 passed**; регрессы интеграционных точек
+(`test_webhooks`, `test_plane_status_model`, `test_plane_sync_labels`, `test_config`,
+`test_plane_author`, `test_stage_visibility`) — зелёные; машинные анти-дрейф доки
+(`test_system_docs`, `test_bundled_setup_doc`, `test_lite_setup_doc`) — зелёные.
+
+Соответствие ТЗ/ADR — полное; control-path не тронут (AC-10 подтверждён: `git diff` не затрагивает
+`src/stages.py`/`src/qg/checks.py`; `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict/схемы
+существующих таблиц — байт-в-байт). Качество кода высокое.
+
+**Единственный блокер — ось «документация»:** инженерный справочник, CHANGELOG, README, ADR
+(work-item + сквозной adr-0054), онбординг/Lite/Bundled-доки обновлены образцово, **но
+бизнес-витрина `docs/overview/` не обновлена** под новую операторскую функциональность. По
+CLAUDE.md правило #6 / ORCH-011 это **P1 → REQUEST_CHANGES**.
+
+## Findings
+
+### P0 — Blocker
+- (нет)
+
+### P1 — Must fix
+- [ ] **Витрина системы `docs/overview/` не обновлена под новую операторскую способность «Оценка»**
+  (CLAUDE.md правило #6 / **ORCH-011**; ось «обзорные доки» reviewer-промпта). PR вводит новый
+  **операторский Plane-статус «Оценка»** и новую пользовательскую способность (прогноз
+  стоимости/времени/токенов/сложности до отправки задачи в работу). ADR-001 (D4) и CHANGELOG сами
+  называют его *«третьим членом семейства action-статусов STOP/Confirm Deploy»*. Витрина при этом:
+  - `docs/overview/tech-pipeline.md:134–135` — «Управляющих статусов **ровно три**: запуск в работу,
+    Approved/Confirm Deploy (человеческие гейты) и STOP» — формулировка устарела/вводит в
+    заблуждение: на доске появился ещё один операторский статус-жест, не отражённый здесь.
+  - `docs/overview/tech-integrations.md:11–12` — «управляют конвейером только машина стадий и **три
+    управляющих статуса** (запуск, человеческие гейты, STOP)» — то же.
+  - `docs/overview/business.md` — перечисляет бизнес-способности (включая отмену STOP, `business.md:43/97`),
+    но **не упоминает оценку задачи** — прямую бизнес-ценность, заявленную в ADR «Последствия»
+    («оператор видит прогноз … до отправки задачи в работу»).
+  - `docs/overview/presentation.md` — перечисляет операторские жесты (Confirm Deploy/STOP/Bug,
+    строки 82/85/139), «Оценка» отсутствует.
+  **Прецедент:** STOP (ORCH-090), Confirm Deploy (ORCH-059), лейбл `Bug` (ORCH-019),
+  autoApprove/autoDeploy (ORCH-089) — все присутствуют в витрине. «Оценка» — того же класса
+  операторская функциональность и должна быть в витрине **в этом же PR**.
+  **Fix:** добавить «Оценку» в `docs/overview/` (минимум: способность в `business.md` +
+  упоминание статуса/жеста в `tech-pipeline.md` § статусной модели и `tech-integrations.md`;
+  пересмотреть формулировку «ровно три статуса»), консистентно с тем, как уже поданы STOP/Bug/
+  Confirm Deploy. Машинные факты витрины (`tests/test_system_docs.py`) при этом держать зелёными.
+
+### P2 — Should fix
+- (нет)
+
+### P3 — Nice-to-have
+- [ ] `tests/test_orch020_estimator.py:532–534` (TC-20) — ассерт цикла по `STAGE_TRANSITIONS`
+  заканчивается `... or True` и потому **никогда не падает** (тавтология, мёртвая проверка).
+  Содержательные проверки оси AC-10 в этом же тесте (строки 531/537) валидны; тавтологичную строку
+  стоит ужесточить (например, проверить, что ни один таргет ребра не равен `estimate`) или удалить.
+- [ ] `src/plane_sync.py::_patch_issue_fields` — PATCH полей issue (`point`/`estimate_point`)
+  проходит guard с `plane_write_guard.OP_STATE`, хотя это не смена state. Функционально безопасно
+  (решение guard'а зависит от проекта sandbox/prod, не от op-метки; op влияет лишь на аудит-лог),
+  но метка семантически неточна. Опционально — ввести/использовать op-константу для field-PATCH
+  ради точности аудита.
+
+## Документация
+
+**Обновлено в PR (корректно):**
+- `docs/architecture/README.md` — новый компонент «Task estimator», подробная секция «Оценка задачи
+  (ORCH-020)», таблица `task_estimates` в data-model, эндпоинты `POST/GET /estimate`, блок
+  `estimator` в `GET /queue`, статусная модель.
+- `docs/work-items/ORCH-020/06-adr/ADR-001-…` + сквозной `docs/architecture/adr/adr-0054-…`.
+- `CHANGELOG.md` (`[Unreleased]`), `README.md` (env-таблица `ORCH_ESTIMATOR_*`).
+- `docs/operations/ONBOARDING.md`, `docs/deployment/LITE_SETUP.md`, `docs/deployment/BUNDLED_SETUP.md`
+  + анти-дрейф тесты (22→23 статуса, сверка импортом `_PLANE_NAME_TO_KEY`).
+- `scripts/onboard_project.py` — 23-й статус «Оценка» (группа `unstarted`, не терминальная).
+
+**Требует обновления (см. P1):**
+- `docs/overview/` (бизнес-витрина) — не отражает новую операторскую способность/статус «Оценка»;
+  устаревшая формулировка «управляющих статусов ровно три». Это и есть блокер вердикта.
+</content>
+</invoke>

docs/work-items/ORCH-108/00-business-request.md

@@ -0,0 +1,7 @@
+# Business Request: FAQ: как использовать STOP для отмены задачи
+
+Work Item ID: ORCH-108
+
+## Description
+
+_(описание отсутствует в источнике)_

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

@@ -0,0 +1,181 @@
+---
+work_item: ORCH-108
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-17
+model_used: claude-opus-4-8
+---
+
+# 01 — BRD (бизнес-требования): ORCH-108 — FAQ: как использовать STOP для отмены задачи
+
+Work Item: **ORCH-108** · Repo: **orchestrator** (self-hosting) · Стадия: analysis
+Тип: документация (пользовательский FAQ). Объём — **только аналитик** (docs-only, без правки `src/**`).
+
+---
+
+## 1. Бизнес-контекст и проблема
+
+Механизм отмены задачи через выделенный Plane-статус **STOP** реализован (ORCH-090,
+`docs/architecture/adr/adr-0026-stop-cancel-task.md`): оператор переводит задачу в статус STOP, и
+оркестратор останавливает агента, снимает job'ы с очереди, прибирает ветку/worktree и переводит
+задачу в терминальное состояние `cancelled`. **Но пользовательской документации «как этим
+пользоваться» нет.** Упоминания STOP разрознены и адресованы разным читателям:
+- `docs/overview/business.md` — «Сценарий 6: остановить задачу» (витрина, 1 абзац);
+- `docs/overview/tech-pipeline.md` — «Отмена: STOP → `cancelled`» (инженерный обзор);
+- ADR ORCH-090 — глубокое архитектурное обоснование (не для конечного пользователя).
+
+Пользователь доски Plane (тот, кто заводит/ведёт задачи) не имеет **единой пошаговой инструкции**:
+что именно делает STOP, что происходит с веткой/статусом/уведомлениями, что будет, если нажать STOP
+во время деплоя, откатывается ли уже влитый в `main` код, и как перезапустить отменённую задачу.
+Из-за этого вероятны ошибочные ожидания (например: «STOP откатит мой код из прода» — **неверно**) и
+лишние обращения к оператору.
+
+**Боль/риск, который закрываем:** отсутствие самодостаточного FAQ → неверная ментальная модель STOP
+→ ошибочные действия на проде (self-hosting: один инстанс обслуживает все проекты) и нагрузка на
+оператора.
+
+**Установленные факты (сверено по коду, не изобретать):**
+- Маршрут STOP: `src/webhooks/plane.py::handle_issue_updated` распознаёт логический ключ `stop`
+  (fail-closed: на доске без статуса STOP ветка не активируется) → `handle_stop` →
+  `src/stage_engine.py::cancel_task`.
+- `cancel_task` (сверено, `src/stage_engine.py:2443`):
+  1. **Идемпотентно** — отсутствующая или уже терминальная (`done`/`cancelled`) задача → no-op.
+  2. **Критичное окно** (`src/cancel.py::in_critical_window`) — задача в необратимой фазе
+     merge/deploy → **отложенная отмена** (`cancel_requested_at`, снимаются только `queued`-job'ы,
+     алерт «⏸️ … отложена»; finalizer применяет отмену после честного завершения шага). STOP
+     **никогда** не трогает `main`, не делает force-push, не рестартит прод-контейнер.
+  3. **Полный сброс** (вне критичного окна) — SIGTERM агента (graceful-каскад), все job'ы →
+     терминальный `cancelled`, очистка deploy-state + освобождение merge-lease, снятие worktree,
+     удаление **рабочей** Gitea-ветки (**не** `main`, без force-push), тумбстон натуральных ключей +
+     `stage='cancelled'`. **Docs-артефакты сохраняются.**
+  4. **Наблюдаемость** — Telegram «🛑 … задача ОТМЕНЕНА (STOP)» + Plane-комментарий + обновление
+     карточки.
+- **Перезапуск с нуля** — только «To Analyse» (тумбстон ключей → `get_task_by_plane_id` вернёт
+  `None` → создаётся свежая задача от актуального `origin/main`). Релонч середины пайплайна закрыт:
+  «To Analyse» на существующей не-`analysis` задаче → no-op + подсказка «STOP → To Analyse».
+- **Простой на `deploy` в ожидании `Confirm Deploy`** (lease держится, но актор не бежит) — **не**
+  критичен → немедленный полный сброс (ORCH-090 review P1).
+- Конфиг: `stop_status_enabled` (kill-switch), `stop_status_repos` (CSV; пусто → все репо). При
+  выключенном флаге / отсутствии статуса STOP — fail-safe no-op.
+- Наблюдаемость для оператора: read-only блок `stop` в `GET /queue` (`src/cancel.py::snapshot`):
+  `enabled`/`repos`/счётчик `cancelled`/`deferred_pending`/последние отмены.
+
+> **Уточнение к формулировке бизнес-запроса.** В описании сказано: «орк запускает cancel_request,
+> откат, затем cancelled». Здесь «откат» = **сброс прогресса задачи** (снятие job'ов, удаление
+> рабочей ветки/worktree, возврат задачи в терминал `cancelled`), а **НЕ** git-revert уже влитого в
+> `main` кода. `cancel_request` — это путь **отложенной** отмены в критичном окне
+> (`cancel_requested_at`), он срабатывает **не всегда**, а только если STOP пришёл во время
+> необратимого шага. FAQ обязан развести эти понятия явно (см. BR-4, BR-5).
+
+---
+
+## 2. Объём (scope)
+
+### В объёме
+- Создать **пользовательский FAQ** о статусе STOP — единый, самодостаточный, пошаговый документ для
+  пользователя доски Plane.
+- FAQ покрывает: назначение STOP; как отменить задачу; что происходит пошагово (агент, job'ы,
+  ветка/worktree, статус, уведомления); поведение в критичном окне merge/deploy (отложенная отмена);
+  явный ответ «STOP не откатывает влитый в `main` код»; как перезапустить отменённую задачу
+  («To Analyse»); идемпотентность повторного STOP; что делать, если STOP «не сработал»
+  (инфра-предусловие — статус STOP на доске, kill-switch); где увидеть результат (Telegram /
+  Plane-комментарий / `GET /queue`).
+- Перекрёстные ссылки между новым FAQ и существующими упоминаниями STOP (витрина / инженерный
+  обзор), без дублирования источника истины.
+
+### Вне объёма
+- Любые изменения кода `src/**`, поведения STOP, `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/схемы БД.
+  Это **docs-only** задача; функциональность STOP уже реализована (ORCH-090) и не меняется.
+- Изменение архитектуры/механики отмены, добавление новых статусов/эндпоинтов.
+- Перевод FAQ на другие языки, видео/скриншоты-гайды.
+- Документирование смежных гейтов (Confirm Deploy / Approved) сверх ссылки-разграничения «STOP ≠
+  Confirm Deploy».
+
+---
+
+## 3. Заинтересованные стороны
+- **Заказчик:** владелец продукта (нужен понятный пользовательский FAQ по STOP).
+- **Затрагивает:** пользователей доски Plane (заводят/ведут/отменяют задачи), оператора
+  (меньше обращений), будущих внешних операторов Lite/Bundled-тиража.
+- **Принимает результат:** reviewer (стадия `review`) — проверяет наличие, полноту и фактическую
+  корректность FAQ против кода.
+
+---
+
+## 4. Бизнес-требования (BR)
+
+- **BR-1 — Единый пользовательский FAQ.** Существует один самодостаточный документ-FAQ о статусе
+  STOP, написанный для пользователя доски Plane (не для разработчика), в формате «вопрос → ответ».
+- **BR-2 — Пошаговая инструкция отмены.** FAQ объясняет, как отменить задачу (перевести issue в
+  статус STOP на доске) и что для этого нужно (статус STOP должен существовать на доске).
+- **BR-3 — Что происходит при STOP.** FAQ описывает наблюдаемые пользователем последствия: агент
+  останавливается, job'ы снимаются, рабочая ветка/worktree удаляются, задача переходит в
+  `cancelled`, приходит уведомление в Telegram и комментарий в Plane; **docs-артефакты задачи
+  сохраняются**.
+- **BR-4 — Отложенная отмена в критичном окне.** FAQ объясняет: если STOP нажат во время
+  необратимого шага (слияние/выкладка), отмена **откладывается** до честного завершения шага;
+  `main`/прод при этом не трогаются.
+- **BR-5 — STOP ≠ откат прод-кода.** FAQ содержит **явный** ответ: STOP сбрасывает незавершённый
+  прогресс задачи, но **не откатывает** код, уже влитый в `main`/прод (revert — отдельная задача).
+- **BR-6 — Перезапуск отменённой задачи.** FAQ объясняет: отменённую задачу нельзя «продолжить с
+  середины»; перезапуск — только «To Analyse», который создаёт задачу **с нуля** (новая ветка от
+  актуального `main`).
+- **BR-7 — Идемпотентность и «не сработало».** FAQ объясняет: повторный STOP по уже отменённой/
+  завершённой задаче безопасен (no-op); если STOP «ничего не сделал» — вероятные причины (статус
+  STOP не заведён на доске / задача уже терминальна / отмена отключена для репо).
+- **BR-8 — Где увидеть результат.** FAQ указывает источники подтверждения отмены: карточка
+  Telegram, комментарий в Plane, read-only блок `stop` в `GET /queue`.
+- **BR-9 — Согласованность с витриной.** FAQ не противоречит существующим упоминаниям STOP в
+  `docs/overview/business.md` и `docs/overview/tech-pipeline.md`; ссылки связывают их без
+  дублирования источника истины.
+
+---
+
+## 5. Нефункциональные требования (NFR)
+
+- **NFR-1 — Docs-only, нулевой рантайм-риск.** Никаких изменений `src/**`, конвейера, гейтов, схемы
+  БД. Self-hosting-безопасно: задача не деплоит/не рестартит прод/не трогает `main`.
+- **NFR-2 — Фактическая точность.** Каждое утверждение FAQ verifiable против кода (`src/cancel.py`,
+  `src/stage_engine.py::cancel_task`, `src/webhooks/plane.py`, `src/config.py`). Запрещены неверные
+  обещания (например «STOP откатит прод»).
+- **NFR-3 — Язык и аудитория.** Русский, тон — пользовательский (без требования читать код/ADR);
+  термины пайплайна поясняются простыми словами.
+- **NFR-4 — Сопровождаемость / анти-дрейф.** Структуру FAQ закрывает детерминированный структурный
+  тест (без сети/LLM/subprocess), по образцу `tests/test_lite_setup_doc.py`, чтобы будущие правки не
+  «отклеивали» FAQ от фактов.
+- **NFR-5 — Без форка источника истины.** FAQ ссылается на канон (ADR ORCH-090, инженерный обзор), а
+  не копирует его дословно; машинные детали — ссылками.
+
+---
+
+## 6. Допущения и ограничения
+
+- **Допущение A1 (размещение).** FAQ размещается как новый документ `docs/operations/FAQ_STOP.md`
+  (раздел эксплуатации/операторских runbook'ов — там же `ONBOARDING.md`, `PHANTOM_MERGE_RUNBOOK.md`).
+  Это **разумный дефолт** исходя из аудитории «оператор/пользователь доски»; точное имя/раздел
+  reviewer/architect может скорректировать, но это не блокирует анализ (не сигнальный вопрос).
+- **Допущение A2 (язык).** Русский — основной язык пользовательской документации проекта
+  (соответствует `docs/overview/*`).
+- **Ограничение C1.** Поведение STOP фиксировано ORCH-090; FAQ его **документирует**, а не меняет.
+  Если по ходу обнаружится расхождение «доки vs код» — это дефект, заводится отдельно (правило
+  агентов №4: не комментировать ТЗ задним числом, возвращать в анализ).
+- **Ограничение C2.** Никаких блокирующих неоднозначностей не выявлено → файл `01-questions.md`
+  **не создаётся** (ORCH-120): сделанных допущений (A1/A2) достаточно для корректного пакета.
+
+---
+
+## 7. Критерии успеха
+
+Документ-FAQ создан, покрывает все темы BR-1…BR-9, фактически согласован с кодом, перекрёстно связан
+с витриной, и закрыт структурным анти-дрейф тестом. Полный регресс `tests/` остаётся зелёным.
+Детальные PASS/FAIL — в `03-acceptance-criteria.md`.
+
+## 8. Риски
+
+- **R1 — Дрейф «доки ↔ код».** Будущая правка STOP сделает FAQ неверным. Митигейшн — структурный
+  тест (NFR-4) + правило «правишь STOP → обнови FAQ в том же PR».
+- **R2 — Ошибочное размещение/дубль.** FAQ продублирует витрину вместо ссылки. Митигейшн — BR-9 +
+  AC на перекрёстные ссылки.
+- Детали/полный перечень — `10-tech-risks.md` (заполняет архитектор; для docs-only задачи риски
+  минимальны).

docs/work-items/ORCH-108/02-trz.md

@@ -0,0 +1,189 @@
+---
+work_item: ORCH-108
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-17
+model_used: claude-opus-4-8
+---
+
+# 02 — ТЗ (TRZ): ORCH-108 — FAQ: как использовать STOP для отмены задачи
+
+Work Item: **ORCH-108** · Repo: **orchestrator** (self-hosting) · Стадия: analysis
+
+> ТЗ описывает **конкретные изменения к реализации**, выведенные из BRD и фактического кода.
+> Это **docs-only** задача: код `src/**` и поведение STOP не меняются. Источник истины поведения —
+> ORCH-090 (`adr-0026`); здесь — требования к **документации** этого поведения.
+> Архитектурное обоснование (если потребуется) — задача архитектора (`06-adr`).
+
+## 1. Сводка изменения
+
+Создать пользовательский **FAQ по статусу STOP** — новый Markdown-документ
+`docs/operations/FAQ_STOP.md` в формате «вопрос → ответ», для пользователя доски Plane. Добавить
+перекрёстные ссылки из существующих упоминаний STOP (витрина / инженерный обзор) на FAQ. Закрыть
+структуру FAQ детерминированным анти-дрейф тестом. **Никаких изменений `src/**`, конвейера, гейтов,
+схемы БД, API.** Полный черновик содержания FAQ — в Приложении A (готов к переносу разработчиком;
+объём «только аналитик» → существенное наполнение сделано на стадии анализа).
+
+## 2. Задействованные модули / пути
+
+| Путь | Действие |
+|------|----------|
+| `docs/operations/FAQ_STOP.md` | **создать** — пользовательский FAQ по STOP (основной deliverable; содержание — Приложение A) |
+| `docs/overview/business.md` | изменить — добавить ссылку «Подробнее: FAQ по STOP» в «Сценарий 6: остановить задачу» |
+| `docs/overview/tech-pipeline.md` | изменить — добавить ссылку на FAQ в раздел «Отмена: STOP → `cancelled`» |
+| `CHANGELOG.md` | изменить — запись `docs: ORCH-108 FAQ по статусу STOP` |
+| `tests/test_faq_stop_doc.py` | **создать** — структурный анти-дрейф тест FAQ (образец `tests/test_lite_setup_doc.py`) |
+
+**Описываемые (read-only) модули — FAQ их излагает, НЕ меняет** (для верификации фактов reviewer'ом):
+- `src/webhooks/plane.py` — `handle_issue_updated` (распознавание ключа `stop`, fail-closed),
+  `handle_stop` (делегирование в `cancel_task`), `handle_status_start` (гейт релонча: «To Analyse»
+  перезапускает только с нуля, не середину пайплайна).
+- `src/stage_engine.py::cancel_task` — оркестрация отмены (идемпотентность / критичное окно /
+  полный сброс / наблюдаемость).
+- `src/cancel.py` — `applies` (kill-switch + repo-scope), `in_critical_window` (классификация
+  необратимого окна), `snapshot` (блок `stop` в `GET /queue`).
+- `src/config.py` — `stop_status_enabled` (env `ORCH_STOP_STATUS_ENABLED`), `stop_status_repos`
+  (env `ORCH_STOP_STATUS_REPOS`, CSV; пусто → все репо).
+- `src/main.py` — read-only блок `stop` в `GET /queue`.
+
+## 3. Функциональные требования
+
+### FR-1 — Документ FAQ существует и адресован пользователю (BR-1)
+Создать `docs/operations/FAQ_STOP.md`: H1-заголовок про STOP, вводный абзац «для кого/зачем», далее
+секции «вопрос → ответ». Тон — пользовательский (без требования читать код). Язык — русский.
+
+### FR-2 — Обязательные секции FAQ (BR-2…BR-8)
+FAQ содержит как минимум следующие тематические секции (заголовки — стабильные якоря для теста
+NFR-4 / TC-02), каждая отвечает на свой вопрос:
+1. **«Что делает статус STOP?»** — назначение: отмена + сброс прогресса задачи.
+2. **«Как отменить задачу?»** — перевести issue в статус **STOP** на доске Plane; предусловие —
+   статус STOP заведён на доске.
+3. **«Что происходит, когда я нажимаю STOP?»** — пошагово: агент останавливается → job'ы снимаются
+   → рабочая ветка и worktree удаляются → задача переходит в `cancelled` → приходит уведомление в
+   Telegram и комментарий в Plane. **Docs-артефакты задачи сохраняются.**
+4. **«Что если задача в этот момент сливается или деплоится?»** — отложенная отмена: отмена
+   откладывается до честного завершения необратимого шага; `main`/прод не трогаются.
+5. **«Откатит ли STOP уже выложенный код?»** — **Нет.** STOP сбрасывает незавершённый прогресс
+   задачи, но не делает git-revert уже влитого в `main`/прод кода (это отдельная задача).
+6. **«Как перезапустить отменённую задачу?»** — только через «To Analyse»; задача создаётся **с
+   нуля** (новая ветка от актуального `main`); «продолжить с середины» нельзя.
+7. **«Я нажал STOP, но ничего не произошло — почему?»** — вероятные причины: статус STOP не заведён
+   на доске (fail-closed no-op); задача уже завершена/отменена (идемпотентный no-op); отмена
+   отключена для репозитория (`stop_status_enabled`/`stop_status_repos`).
+8. **«Где увидеть, что задача отменена?»** — карточка Telegram («🛑 … ОТМЕНЕНА (STOP)»), комментарий
+   в Plane, read-only блок `stop` в `GET /queue`.
+
+### FR-3 — Разграничение STOP ↔ другие управляющие статусы (BR-9)
+FAQ кратко разграничивает STOP и человеческие гейты `Approved`/`Confirm Deploy` (STOP — отмена, не
+одобрение/деплой), ссылкой на инженерный обзор, без переписывания их семантики.
+
+### FR-4 — Перекрёстные ссылки без дублирования (BR-9, NFR-5)
+- В `docs/overview/business.md` («Сценарий 6») и `docs/overview/tech-pipeline.md` («Отмена: STOP →
+  `cancelled`») добавить ссылку на `FAQ_STOP.md`.
+- В FAQ — обратные ссылки на инженерный обзор и ADR ORCH-090 как на источник истины поведения.
+- **Не дублировать** машинные детали (маркеры/lease/тумбстон) — давать ссылками.
+
+### FR-5 — Фактическая корректность (NFR-2)
+Каждое утверждение FAQ соответствует коду на момент написания (см. §2 read-only модули). Запрещены
+утверждения, противоречащие коду — в частности: «STOP откатывает прод», «STOP трогает `main`/делает
+force-push», «отменённую задачу можно продолжить с середины», «STOP мгновенно убивает идущий
+деплой».
+
+### FR-6 — Анти-дрейф тест (NFR-4)
+Создать `tests/test_faq_stop_doc.py` (детерминированный, без сети/LLM/subprocess; только парсинг
+файла): FAQ существует; присутствуют все обязательные секции-якоря (FR-2); присутствуют ключевые
+факты-«кирпичи» (STOP, `cancelled`, «To Analyse», «main … не», отложенная/deferred); присутствуют
+перекрёстные ссылки (FR-4); отсутствуют запрещённые неверные утверждения (FR-5, негативный скан).
+
+## 4. Изменения API
+Нет. (FAQ лишь упоминает существующий read-only `GET /queue` блок `stop`.)
+
+## 5. Изменения схемы БД
+Нет.
+
+## 6. Требования к новым/изменённым QG checks
+Нет. `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict — не затрагиваются.
+Замечание по coverage-гейту (ORCH-027): docs-only изменение не добавляет строк `src/` → базовая
+линия покрытия не меняется; новый `tests/test_faq_stop_doc.py` не покрывает `src/` (структурный
+тест документа) и на метрику не влияет.
+
+## 7. Совместимость / регресс
+- **Обратная совместимость — полная.** Только добавление/правка docs + новый структурный тест.
+  Поведение рантайма байт-в-байт прежнее; kill-switch не требуется (нет исполняемого кода).
+- **Self-hosting-безопасно.** Не деплоит/не рестартит прод/не трогает `main`; реальный прод-деплой
+  этой задачи безопасен (docs).
+- **Регресс.** Полный `tests/` остаётся зелёным; новый тест читает только файл FAQ.
+- **Сопровождение (норматив).** Правишь поведение STOP (`src/cancel.py`/`cancel_task`/маршрут
+  `stop`) → обнови `docs/operations/FAQ_STOP.md` в том же PR (правило агентов №2 / №6: reviewer
+  требует обновлённую доку).
+
+---
+
+## Приложение A — Черновик содержания FAQ (готов к переносу в `docs/operations/FAQ_STOP.md`)
+
+> Нормативный ориентир содержания (объём «только аналитик»). Разработчик переносит как тело
+> документа; точные формулировки можно полировать, фактическую часть менять нельзя без возврата в
+> анализ (правило №4).
+
+```markdown
+# FAQ: отмена задачи через статус STOP
+
+Эта страница — для пользователя доски Plane. Она объясняет, что делает статус **STOP**, как им
+безопасно остановить задачу и чего от него ждать. Технические детали механизма — в
+[инженерном обзоре](../overview/tech-pipeline.md#отмена-stop--cancelled) и
+[ADR ORCH-090](../work-items/ORCH-090/06-adr/ADR-001-stop-cancel-task.md).
+
+## Что делает статус STOP?
+STOP — это «кнопка отмены» задачи. Перевод задачи в статус STOP останавливает работу агента, снимает
+задачу с очереди, прибирает рабочие материалы (ветку и worktree) и помечает задачу отменённой
+(`cancelled`). Безопасно нажимать даже посреди конвейера.
+
+## Как отменить задачу?
+Переведите issue в статус **STOP** на доске Plane — так же, как меняете любой другой статус.
+Предусловие: на доске должен быть заведён статус **STOP** (группа `cancelled`). Если его нет, STOP
+не сработает (см. «ничего не произошло»).
+
+## Что происходит, когда я нажимаю STOP?
+По шагам:
+1. Активный агент останавливается (мягкая остановка процесса).
+2. Все задачи в очереди по этой задаче снимаются и больше не перезапускаются.
+3. Рабочая ветка задачи и её worktree удаляются. **Ветка `main` и прод никогда не трогаются.**
+4. Задача переходит в терминальное состояние `cancelled`.
+5. Приходит уведомление в Telegram («🛑 … задача ОТМЕНЕНА (STOP)») и комментарий в Plane.
+
+**Документы задачи (анализ, ТЗ и т.д.) сохраняются** — удаляются только рабочая ветка и worktree.
+
+## Что если задача в этот момент сливается или деплоится?
+Если STOP пришёл во время необратимого шага (слияние в `main` или выкладка), отмена **аккуратно
+откладывается** до честного завершения этого шага. Вы увидите уведомление «⏸️ … отмена отложена».
+`main` и прод при этом не трогаются; после завершения шага отмена применяется автоматически.
+
+## Откатит ли STOP уже выложенный код?
+**Нет.** STOP сбрасывает **незавершённый прогресс** задачи (ветку/worktree/очередь), но **не
+откатывает** код, который уже влит в `main` или выложен в прод. Откат выложенного — это отдельная
+задача (revert), STOP её не делает.
+
+## Как перезапустить отменённую задачу?
+Отменённую задачу нельзя «продолжить с середины». Чтобы начать заново, переведите её в статус
+**«To Analyse»** — задача будет создана **с нуля** (новая ветка от актуального `main`, новый анализ).
+
+## Я нажал STOP, но ничего не произошло — почему?
+Вероятные причины:
+- На доске **нет статуса STOP** — переход не распознаётся (безопасный no-op). Заведите статус STOP
+  (группа `cancelled`).
+- Задача **уже завершена или уже отменена** — повторный STOP ничего не меняет (это нормально).
+- Отмена **отключена для репозитория** настройкой (`stop_status_enabled` / `stop_status_repos`) —
+  обратитесь к оператору.
+
+## Где увидеть, что задача отменена?
+- Карточка задачи в **Telegram** покажет «🛑 … ОТМЕНЕНА (STOP)».
+- В **Plane** появится комментарий об отмене.
+- Оператор может увидеть отмену в служебной странице состояния `GET /queue` (блок `stop`).
+
+## STOP, Approved и Confirm Deploy — в чём разница?
+- **STOP** — отменить задачу.
+- **Approved** — одобрить артефакт анализа (двигает задачу дальше), деплой не запускает.
+- **Confirm Deploy** — подтвердить прод-выкладку.
+Подробнее об управляющих статусах — в [инженерном обзоре](../overview/tech-pipeline.md).
+```

docs/work-items/ORCH-108/03-acceptance-criteria.md

@@ -0,0 +1,141 @@
+---
+work_item: ORCH-108
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-17
+model_used: claude-opus-4-8
+---
+
+# 03 — Критерии приёмки (Acceptance Criteria): ORCH-108 — FAQ: как использовать STOP
+
+Work Item: **ORCH-108** · Repo: **orchestrator** · Стадия: analysis
+
+Формат: каждый критерий имеет **PASS** (что должно быть истинно для приёмки) и **FAIL** (что
+считается провалом). Reviewer проверяет их буквально по файлам репозитория.
+
+---
+
+## AC-1 — FAQ-документ существует и адресован пользователю
+
+**Условие:** создан `docs/operations/FAQ_STOP.md` в формате «вопрос → ответ» для пользователя Plane.
+- **PASS:** файл существует; есть H1 про STOP и вводный абзац «для кого/зачем»; тон
+  пользовательский (не требует чтения кода); язык русский.
+- **FAIL:** файла нет; либо это разработческий/архитектурный текст, а не пользовательский FAQ; либо
+  нет формата «вопрос → ответ».
+
+---
+
+## AC-2 — Покрыты все обязательные темы
+
+**Условие:** FAQ содержит секции, отвечающие на 8 обязательных вопросов TRZ §FR-2.
+- **PASS:** присутствуют все темы — (1) что делает STOP; (2) как отменить; (3) что происходит
+  пошагово; (4) отложенная отмена в критичном окне; (5) STOP не откатывает прод-код; (6) перезапуск
+  через «To Analyse» с нуля; (7) «ничего не произошло — почему»; (8) где увидеть результат.
+- **FAIL:** отсутствует хотя бы одна из тем (1)–(8).
+
+---
+
+## AC-3 — Пошаговые последствия STOP описаны верно
+
+**Условие:** тема (3) перечисляет наблюдаемые последствия согласно `cancel_task`.
+- **PASS:** перечислены — остановка агента; снятие job'ов; удаление рабочей ветки и worktree; явное
+  «`main`/прод не трогаются»; переход в `cancelled`; уведомление Telegram + комментарий Plane; явное
+  «docs-артефакты сохраняются».
+- **FAIL:** пропущен или искажён любой из этих пунктов (например утверждается, что удаляются docs,
+  или что трогается `main`).
+
+---
+
+## AC-4 — Отложенная отмена в критичном окне
+
+**Условие:** тема (4) корректно описывает поведение при STOP во время merge/deploy.
+- **PASS:** сказано, что отмена **откладывается** до честного завершения необратимого шага; что
+  `main`/прод не трогаются; что после завершения шага отмена применяется.
+- **FAIL:** утверждается мгновенное прерывание деплоя/слияния, либо что STOP убивает идущий
+  необратимый шаг, либо тема отсутствует.
+
+---
+
+## AC-5 — STOP ≠ откат прод-кода (явный ответ)
+
+**Условие:** тема (5) явно разводит «сброс прогресса» и «revert выложенного».
+- **PASS:** есть явное «Нет»: STOP **не откатывает** код, уже влитый в `main`/прод; revert — отдельная
+  задача.
+- **FAIL:** FAQ обещает/намекает, что STOP откатит прод-код, либо тема отсутствует.
+
+---
+
+## AC-6 — Перезапуск отменённой задачи
+
+**Условие:** тема (6) описывает перезапуск.
+- **PASS:** сказано, что перезапуск — только «To Analyse»; задача создаётся **с нуля** (новая ветка
+  от актуального `main`); «продолжить с середины» нельзя.
+- **FAIL:** утверждается возможность продолжить отменённую задачу с середины, либо неверный
+  механизм перезапуска, либо тема отсутствует.
+
+---
+
+## AC-7 — «Не сработало» и идемпотентность
+
+**Условие:** тема (7) перечисляет причины no-op.
+- **PASS:** перечислены — статус STOP не заведён на доске (fail-closed); задача уже терминальна
+  (идемпотентный no-op); отмена отключена для репо (`stop_status_enabled`/`stop_status_repos`).
+- **FAIL:** причины не описаны или описаны неверно (например, утверждается, что повторный STOP
+  ломает задачу).
+
+---
+
+## AC-8 — Перекрёстные ссылки без дублирования
+
+**Условие:** FAQ связан с витриной/обзором двусторонними ссылками (TRZ §FR-4).
+- **PASS:** `docs/overview/business.md` («Сценарий 6») и `docs/overview/tech-pipeline.md` («Отмена:
+  STOP → `cancelled`») содержат ссылку на `FAQ_STOP.md`; FAQ ссылается на инженерный обзор и ADR
+  ORCH-090 как на источник истины; машинные детали не дублируются, а даются ссылками.
+- **FAIL:** ссылок нет (FAQ-«сирота»); либо FAQ дословно копирует ADR/обзор вместо ссылки.
+
+---
+
+## AC-9 — Фактическая корректность (нет ложных утверждений)
+
+**Условие:** утверждения FAQ соответствуют коду (`src/cancel.py`, `src/stage_engine.py::cancel_task`,
+`src/webhooks/plane.py`, `src/config.py`); запрещённых неверных утверждений нет.
+- **PASS:** в FAQ отсутствуют утверждения «STOP трогает `main`/делает force-push», «STOP откатывает
+  прод», «отменённую задачу можно продолжить с середины», «STOP мгновенно убивает идущий деплой».
+- **FAIL:** присутствует хотя бы одно противоречащее коду утверждение.
+
+---
+
+## AC-10 — Docs-only, нулевой рантайм-регресс
+
+**Условие:** изменения ограничены документацией + структурным тестом.
+- **PASS:** `git diff` не затрагивает `src/**`, `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/схему БД;
+  изменены только `docs/**`, `CHANGELOG.md`, `tests/test_faq_stop_doc.py`; полный `tests/` зелёный.
+- **FAIL:** затронут `src/**` или поведение гейтов/конвейера; либо регресс `tests/` красный.
+
+---
+
+## AC-11 — Анти-дрейф тест присутствует и зелёный
+
+**Условие:** структурную целостность FAQ закрывает детерминированный тест (TRZ §FR-6).
+- **PASS:** `tests/test_faq_stop_doc.py` существует; проверяет наличие файла, обязательных
+  секций-якорей, ключевых фактов-«кирпичей», перекрёстных ссылок и отсутствие запрещённых
+  утверждений; не делает сети/LLM/subprocess; проходит зелёным.
+- **FAIL:** теста нет; либо он не детерминирован (сеть/LLM/subprocess); либо красный.
+
+---
+
+## Сводная матрица AC ↔ FR/BR
+| AC | Покрывает |
+|----|-----------|
+| AC-1 | BR-1 / FR-1 |
+| AC-2 | BR-2…BR-8 / FR-2 |
+| AC-3 | BR-3 / FR-2(3) |
+| AC-4 | BR-4 / FR-2(4) |
+| AC-5 | BR-5 / FR-2(5) |
+| AC-6 | BR-6 / FR-2(6) |
+| AC-7 | BR-7 / FR-2(7) |
+| AC-8 | BR-9 / FR-3, FR-4 |
+| AC-9 | NFR-2 / FR-5 |
+| AC-10 | NFR-1 / FR (docs-only), §7 |
+| AC-11 | NFR-4 / FR-6 |

docs/work-items/ORCH-108/04-test-plan.yaml

@@ -0,0 +1,74 @@
+work_item: ORCH-108
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-17
+model_used: claude-opus-4-8
+title: "Анти-дрейф структурного FAQ по статусу STOP (docs-only)"
+framework: pytest
+scope: >
+  Покрывается СТРУКТУРНАЯ целостность и фактическая непротиворечивость нового
+  пользовательского документа docs/operations/FAQ_STOP.md (детерминированно: только
+  парсинг файлов, без сети/LLM/subprocess; образец tests/test_lite_setup_doc.py).
+  Вне покрытия: поведение STOP в рантайме — оно реализовано и протестировано в
+  ORCH-090 (tests/ по cancel_task/cancel.py), эта задача его НЕ меняет (docs-only).
+notes: >
+  Docs-only задача: src/** не меняется, поэтому юнит/интеграционных тестов кода нет —
+  только структурные тесты документа. Полный регресс tests/ должен оставаться зелёным
+  (новый тест читает лишь файлы docs/, на src/-покрытие/coverage-baseline не влияет).
+  Все тесты — type: unit (без сети/LLM/subprocess), модуль tests/test_faq_stop_doc.py.
+
+tests:
+  - id: TC-01
+    type: unit
+    description: "FAQ существует: docs/operations/FAQ_STOP.md присутствует, непустой, есть H1 про STOP и вводный абзац для пользователя (AC-1)."
+    module: tests/test_faq_stop_doc.py
+    expected: PASS
+
+  - id: TC-02
+    type: unit
+    description: "Обязательные секции-якоря присутствуют: все 8 тем FR-2 (что делает STOP / как отменить / пошагово / отложенная отмена / не откатывает прод / перезапуск To Analyse / 'ничего не произошло' / где увидеть) (AC-2)."
+    module: tests/test_faq_stop_doc.py
+    expected: PASS
+
+  - id: TC-03
+    type: unit
+    description: "Пошаговые последствия и сохранность: упомянуты остановка агента, снятие job'ов, удаление рабочей ветки/worktree, переход в cancelled, уведомление Telegram+Plane, явное 'docs сохраняются' (AC-3)."
+    module: tests/test_faq_stop_doc.py
+    expected: PASS
+
+  - id: TC-04
+    type: unit
+    description: "Критичное окно: присутствует факт отложенной отмены (deferred / 'отложена') и явное 'main/прод не трогаются' (AC-4)."
+    module: tests/test_faq_stop_doc.py
+    expected: PASS
+
+  - id: TC-05
+    type: unit
+    description: "STOP ≠ откат прод-кода: присутствует явный отрицательный ответ ('не откатывает' влитый в main/прод код) (AC-5)."
+    module: tests/test_faq_stop_doc.py
+    expected: PASS
+
+  - id: TC-06
+    type: unit
+    description: "Перезапуск: упомянуто 'To Analyse' и создание задачи 'с нуля', отсутствует обещание 'продолжить с середины' (AC-6)."
+    module: tests/test_faq_stop_doc.py
+    expected: PASS
+
+  - id: TC-07
+    type: unit
+    description: "Негативный скан фактов: в FAQ НЕТ запрещённых утверждений — 'откатит прод', 'трогает main/force-push', 'продолжить отменённую с середины', 'мгновенно убивает деплой' (AC-9)."
+    module: tests/test_faq_stop_doc.py
+    expected: PASS
+
+  - id: TC-08
+    type: unit
+    description: "Перекрёстные ссылки: business.md (Сценарий 6) и tech-pipeline.md (Отмена: STOP → cancelled) содержат ссылку на FAQ_STOP.md; FAQ ссылается на инженерный обзор/ADR ORCH-090 (AC-8)."
+    module: tests/test_faq_stop_doc.py
+    expected: PASS
+
+  - id: TC-09
+    type: unit
+    description: "Docs-only регресс-инвариант: полный прогон tests/ зелёный; новый тест не импортирует src/ рантайм и не делает сети/subprocess (AC-10, AC-11)."
+    module: tests/test_faq_stop_doc.py
+    expected: PASS

docs/work-items/ORCH-108/06-adr/ADR-001-faq-stop-placement-and-anti-drift.md

@@ -0,0 +1,173 @@
+---
+work_item: ORCH-108
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-17
+model_used: claude-opus-4-8
+---
+
+# ADR-001: Размещение пользовательского FAQ по STOP и контур анти-дрейфа
+
+Work Item: **ORCH-108** — FAQ: как использовать статус STOP для отмены задачи
+Стадия: **architecture**
+Сквозная регистрация: **N/A — локальное решение задачи** (docs-only; новых QG/стадий/
+компонентов/таблиц нет, маркеры `ORCH-NNN` в `src/**` не вводятся → сквозной
+`docs/architecture/adr/adr-NNNN-*` не требуется; критерий — `docs/_standards/PIPELINE_DOCS.md` §4).
+
+## Статус
+Proposed
+
+## Контекст
+
+Механизм отмены задачи через Plane-статус **STOP** реализован в ORCH-090
+(`docs/architecture/adr/adr-0026-stop-cancel-task.md`, `src/cancel.py`,
+`src/stage_engine.py::cancel_task`, `src/webhooks/plane.py`). Пользовательской
+инструкции «как этим пользоваться» нет — упоминания STOP разрознены и адресованы разным
+читателям (витрина `docs/overview/business.md` «Сценарий 6», инженерный обзор
+`docs/overview/tech-pipeline.md` «Отмена: STOP → `cancelled`», глубокий ADR ORCH-090). Это
+порождает неверную ментальную модель («STOP откатит мой код из прода» — **неверно**) и нагрузку
+на оператора (self-hosting: один инстанс на все проекты).
+
+Аналитик (BRD/TRZ/AC, `ready-for-review`) полностью описал требуемый артефакт и приложил готовый
+черновик содержания (TRZ Приложение A). Это **docs-only** задача: `src/**`, `STAGE_TRANSITIONS`,
+`QG_CHECKS`, `check_*`, схема БД — не меняются; поведение STOP фиксировано ORCH-090 и FAQ его лишь
+**документирует**. Архитектурных решений по существу два: (1) куда положить FAQ в дереве доков и
+(2) как структурно защитить его от дрейфа «доки ↔ код». Остальное — исполнение на стадии
+development.
+
+Факты, сверенные на ветке задачи (read-only):
+- Цели перекрёстных ссылок **существуют**: `docs/overview/business.md` §«Сценарий 6: остановить
+  задачу» (стр. 96), `docs/overview/tech-pipeline.md` §«Отмена: STOP → `cancelled`» (стр. 122),
+  `docs/work-items/ORCH-090/06-adr/ADR-001-stop-cancel-task.md`. Ссылки FR-4 не «висячие».
+- Семантика разделов доков (ORCH-011, `adr-0039`): `overview/` — витрина «что за система»,
+  `architecture/` — инженерный справочник, `deployment/` — «как развернуть у себя»,
+  `operations/` — «как эксплуатировать наш прод» (runbook'и: `ONBOARDING.md`,
+  `PHANTOM_MERGE_RUNBOOK.md`, `STAGING.md`, …).
+- `docs/overview/` — **курируемый плоский каталог из 10 файлов**, чьё содержимое прибито
+  структурным тестом `tests/test_system_docs.py` (витрина — не свалка произвольных доков).
+- Прецедент анти-дрейф теста документа — `tests/test_lite_setup_doc.py` (детерминированный,
+  offline; позитивные якоря-секции + «кирпичи» + кросс-ссылки + негативный скан запрещённых
+  литералов по `FORBIDDEN`).
+
+## Решение
+
+### Сводка
+Размещаем FAQ как **`docs/operations/FAQ_STOP.md`** — пользовательский документ «вопрос → ответ»,
+прилинкованный из витрины/обзора и закрытый детерминированным структурным тестом
+`tests/test_faq_stop_doc.py`. Утверждаем разумный дефолт аналитика (A1) как архитектурное решение,
+с явной фиксацией ключевого нюанса теста — **негативный скан проверяет запрещённые
+утверждения, а не голые подстроки** (иначе он ложно срабатывал бы на предложениях, которые эти же
+термины корректно **отрицают**).
+
+### D1 — Размещение: `docs/operations/FAQ_STOP.md` (BR-1, A1)
+FAQ ложится в `docs/operations/` рядом с операторскими runbook'ами.
+
+Обоснование выбора между тремя кандидатами (аудитория FAQ «пользователь доски + оператор»
+неоднородна, поэтому секция не очевидна):
+- **`docs/overview/` — отвергнуто.** Это курируемая витрина фиксированного состава (10 файлов),
+  защищённая `tests/test_system_docs.py`; добавление отдельного FAQ нарушит инвариант каталога
+  витрины и саму семантику «обзор, а не справочник процедур».
+- **Новый раздел `docs/faq/` — отвергнуто.** Заведение top-level раздела ради одного документа —
+  scope-creep; нет канона/индекса/норматива сопровождения для нового раздела.
+- **`docs/operations/FAQ_STOP.md` — выбрано.** Это де-факто дом человеко-ориентированных процедур
+  и «что делать, если…» (тробл-шутинг STOP в FR-2 п.7 ссылается на `stop_status_enabled`/
+  `stop_status_repos`, а «где увидеть результат» в п.8 — на read-only блок `stop` в `GET /queue`;
+  обе темы — операторская территория). Пользователь доски и оператор на self-hosting сильно
+  пересекаются; именно к operations-доке оператор отсылает пользователя.
+
+Документированная остаточная издержка: лёгкое несоответствие «аудитория-пользователь ↔
+секция-operations». Принимается осознанно (см. «Последствия»); пере-размещение в будущий
+`docs/faq/` остаётся дешёвым (один файл + правка двух ссылок + одного теста).
+
+### D2 — Граница объёма: docs-only, без рантайм-поверхности (NFR-1, AC-10)
+Подтверждаю и фиксирую как архитектурный инвариант:
+- `src/**`, `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, machine-verdict ключи, схема БД — **не
+  трогаются**; kill-switch не требуется (нет исполняемого кода).
+- **`07-infra-requirements.md` — N/A** (топология/контейнеры/сеть не меняются).
+- **`08-data-requirements.md` — N/A** (таблиц/колонок/индексов не добавляется).
+- `docs/architecture/README.md` / `internals.md` — **не обновляются**: задача не затрагивает
+  стадии/QG/компоненты (новый operations-FAQ описывает уже задокументированную фичу ORCH-090, не
+  вводя архитектурных сущностей). Внесение FAQ в архитектурный справочник было бы дублированием
+  источника истины (нарушение NFR-5).
+- Coverage-гейт (ORCH-027): docs-only не добавляет строк `src/` → базовая линия покрытия не
+  меняется; `tests/test_faq_stop_doc.py` — структурный тест документа, `src/` не покрывает и на
+  метрику не влияет.
+
+### D3 — Контур анти-дрейфа: `tests/test_faq_stop_doc.py`, негативный скан на уровне утверждений (NFR-4, FR-6, AC-11)
+Структурный тест по образцу `tests/test_lite_setup_doc.py` — детерминированный, **без сети/LLM/
+subprocess**, только парсинг файла. Обязательный состав проверок:
+1. **Существование** `docs/operations/FAQ_STOP.md`.
+2. **Позитивные якоря** — все 8 обязательных секций-вопросов TRZ §FR-2 присутствуют (заголовки —
+   стабильные якоря; тест матчит по нормализованному заголовку, не по точной пунктуации).
+3. **«Кирпичи»-факты** — присутствуют ключевые токены (`STOP`, `cancelled`, «To Analyse»,
+   «отлож…»/`deferred`, упоминание `GET /queue`/блока `stop`).
+4. **Кросс-ссылки** (FR-4) — ссылка на `tech-pipeline.md` и на ADR ORCH-090 присутствует.
+5. **Негативный скан (КЛЮЧЕВОЙ нюанс).** Запрещённые **утверждения** FR-5 («STOP откатывает
+   прод», «STOP трогает `main`/force-push», «продолжить с середины», «STOP мгновенно убивает
+   деплой») детектируются как **утверждения целиком**, а **НЕ** как голые подстроки. Причина:
+   корректный FAQ закономерно содержит слова `main`, «откатыва…», «force-push», «деплой» внутри
+   **отрицающих** предложений («STOP **не откатывает** … `main`»). Наивный substring-скан по этим
+   словам ложно завалит именно те фразы, которые требование AC-9 предписывает иметь. Реализация:
+   матчить нормативно-запрещённые фразы (например, утверждение отката прод-кода **без**
+   отрицания рядом), либо проверять, что запрещённый токен встречается только в соседстве с
+   отрицанием. Конкретную форму выбирает разработчик; инвариант — **тест не должен фолзить на
+   фактически верном FAQ** и **обязан краснеть на реально ложном утверждении**.
+
+Контракт теста — никогда не делать сеть/LLM/subprocess (как и эталон), чтобы оставаться частью
+обычного зелёного `tests/` без инфра-зависимостей.
+
+### D4 — Целостность ссылок и link-first (FR-4, NFR-5, AC-8)
+Перекрёстные ссылки добавляются **в обе стороны** (витрина/обзор → FAQ; FAQ → обзор + ADR
+ORCH-090). Источник истины поведения остаётся за ADR ORCH-090 и инженерным обзором — FAQ их
+**не форкает** (машинные детали: маркеры/lease/тумбстон — только ссылками). Цели ссылок
+проверены существующими (см. Контекст). Якорь-слаг на секцию обзора
+(`tech-pipeline.md` «Отмена: STOP → `cancelled`») разработчик обязан сверить с фактической
+генерацией якоря при переносе (риск TR-4).
+
+### D5 — Норматив сопровождения (traceability)
+Фиксируется правило: **правишь поведение STOP** (`src/cancel.py` / `cancel_task` / маршрут `stop`
+в `src/webhooks/plane.py`) → **обнови `docs/operations/FAQ_STOP.md` в том же PR** (правило агентов
+№2/№6; reviewer-ось «документация»). Машинный маркер `ORCH-108` в `src/**` НЕ вводится (docs-only),
+поэтому анти-археологии маркеров (`docs/_standards/TRACEABILITY.md`) этот PR не порождает; связь
+«код STOP ↔ FAQ» держится нормативом сопровождения + структурным тестом D3.
+
+## Альтернативы
+- **FAQ в `docs/overview/`** — отвергнуто: курируемая витрина фиксированного состава под
+  `tests/test_system_docs.py`; FAQ ≠ обзорный слайд (см. D1).
+- **Новый раздел `docs/faq/`** — отвергнуто: scope-creep ради одного файла (см. D1).
+- **Без анти-дрейф теста, полагаясь на reviewer** — отвергнуто: NFR-4 требует структурной
+  защиты от дрейфа «доки ↔ код»; ручная проверка не воспроизводима.
+- **Негативный скан по голым подстрокам** — отвергнуто: ложные срабатывания на корректно
+  отрицающих предложениях (см. D3) — это сделало бы тест либо красным на верном FAQ, либо
+  вынудило бы выкинуть из FAQ обязательные явные отрицания.
+- **Сквозной (global) ADR** — отвергнуто: решение не кросс-каттинговое (нет нового QG/стадии/
+  компонента/таблицы; не меняет канон доков как такой).
+
+## Последствия
+- **+** Единый самодостаточный источник для пользователя доски → меньше неверных ожиданий и
+  обращений к оператору (self-hosting-выгода).
+- **+** Структурный тест (D3) делает дрейф «доки ↔ код» воспроизводимо ловимым; норматив D5
+  закрывает процессный пробел.
+- **+** Нулевой рантайм-риск: docs-only, прод-деплой этой задачи безопасен.
+- **−** Лёгкое несоответствие «пользовательская аудитория ↔ секция operations» (D1). Митигейшн:
+  явный вводный абзац «для кого» в FAQ + дешёвое будущее пере-размещение.
+- **−** Риск чрезмерно строгого негативного скана (D3). Митигейшн: матч на уровне утверждений +
+  явный инвариант «не фолзить на верном FAQ» (TR-3).
+- **Откат:** удалить `docs/operations/FAQ_STOP.md` и `tests/test_faq_stop_doc.py`, снять
+  добавленные ссылки из `business.md`/`tech-pipeline.md` и запись из `CHANGELOG.md`. Рантайм не
+  затрагивается.
+
+## Ссылки
+- BRD: `docs/work-items/ORCH-108/01-brd.md`
+- TRZ: `docs/work-items/ORCH-108/02-trz.md` (+ Приложение A — черновик содержания FAQ)
+- Acceptance: `docs/work-items/ORCH-108/03-acceptance-criteria.md`
+- Tech-risks: `docs/work-items/ORCH-108/10-tech-risks.md`
+- Источник истины поведения STOP: `docs/work-items/ORCH-090/06-adr/ADR-001-stop-cancel-task.md`,
+  `docs/architecture/adr/adr-0026-stop-cancel-task.md`
+- Сверено по коду: `src/cancel.py`, `src/stage_engine.py::cancel_task`,
+  `src/webhooks/plane.py` (`handle_issue_updated`/`handle_stop`/`handle_status_start`),
+  `src/config.py` (`stop_status_enabled`/`stop_status_repos`), `src/main.py` (блок `stop` в
+  `GET /queue`)
+- Эталон анти-дрейф теста: `tests/test_lite_setup_doc.py`
+- Семантика разделов доков: `docs/architecture/adr/adr-0039-system-overview-docs-canon.md`

docs/work-items/ORCH-108/10-tech-risks.md

@@ -0,0 +1,39 @@
+---
+work_item: ORCH-108
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-17
+model_used: claude-opus-4-8
+---
+
+# 10 — Технические риски: ORCH-108 — FAQ по статусу STOP
+
+Work Item: **ORCH-108** · Repo: **orchestrator** (self-hosting) · Стадия: architecture
+
+> Информационный документ (гейтом не парсится). Перечисляет риски реализации **docs-only**
+> задачи и их митигейшн. Класс рисков — минимальный: рантайм/конвейер не затрагиваются.
+
+## Реестр рисков
+
+| ID | Риск | Вер. | Влия. | Митигейшн |
+|----|------|------|-------|-----------|
+| TR-1 | **Дрейф «доки ↔ код».** Будущая правка поведения STOP (`src/cancel.py`/`cancel_task`/маршрут `stop`) сделает FAQ неверным. | Сред. | Сред. | Структурный анти-дрейф тест `tests/test_faq_stop_doc.py` (ADR D3) + норматив сопровождения «правишь STOP → обнови FAQ в том же PR» (ADR D5) + reviewer-ось «документация». |
+| TR-2 | **FAQ-«сирота» / дубль источника истины.** FAQ не связан с витриной или дословно копирует ADR/обзор вместо ссылки. | Низ. | Низ. | Link-first (ADR D4): двусторонние ссылки (AC-8), машинные детали — только ссылками; тест проверяет наличие кросс-ссылок. |
+| TR-3 | **Ложно-строгий негативный скан.** Тест ищет запрещённые слова (`main`, «откатыва…», `force-push`) как голые подстроки → краснеет на корректно **отрицающих** предложениях FAQ (которые AC-9 предписывает иметь). | Сред. | Сред. | Негативный скан — на уровне **утверждений**, а не подстрок (ADR D3); инвариант «тест не фолзит на верном FAQ, но краснеет на реально ложном». Зеркало эталона `tests/test_lite_setup_doc.py`. |
+| TR-4 | **Битый якорь кросс-ссылки.** Ссылка `tech-pipeline.md#отмена-stop--cancelled` не совпадёт с фактически генерируемым slug заголовка «Отмена: STOP → `cancelled`». | Низ. | Низ. | Разработчик сверяет slug при переносе (ADR D4); цели секций подтверждены существующими (business.md §«Сценарий 6», tech-pipeline.md §«Отмена», ADR ORCH-090). |
+| TR-5 | **Фактическая неточность FAQ.** Утверждение расходится с кодом (напр. «STOP откатит прод», «убивает деплой мгновенно»). | Низ. | Выс. | NFR-2/FR-5/AC-9: каждое утверждение verifiable против read-only модулей (ADR §Ссылки); reviewer сверяет с кодом; негативный скан (TR-3) ловит запрещённый класс. Содержание выверено аналитиком (TRZ Приложение A). |
+| TR-6 | **Ошибочное размещение раздела.** Аудитория FAQ — «пользователь доски», секция — `operations/` («наш прод»). | Низ. | Низ. | Осознанный компромисс (ADR D1): альтернативы (`overview/` под тестом витрины, новый `docs/faq/`) хуже; вводный абзац «для кого»; будущее пере-размещение дёшево (1 файл + 2 ссылки + 1 тест). |
+
+## Сводный вывод
+
+Доминирующий класс — **дрейф документации** (TR-1) и **хрупкость анти-дрейф теста** (TR-3); оба
+структурно снижены решением D3 (claim-level негативный скан + детерминированный offline-тест) и
+нормативом сопровождения D5. Рантайм-рисков **нет**: задача docs-only, не трогает `src/**`/
+`STAGE_TRANSITIONS`/`QG_CHECKS`/схему БД, не деплоит/не рестартит прод/не трогает `main` →
+self-hosting-безопасна, прод-деплой безвреден.
+
+**Эскалация не требуется.** Не `arch:major-change` (нет новой стадии/компонента/смены БД), возврат
+в анализ не нужен (BRD/TRZ/AC полны и согласованы с кодом; блокирующих неоднозначностей нет —
+`01-questions.md` аналитиком осознанно не создан). Остаточный риск для прод-конвейера —
+**пренебрежимо мал**.

docs/work-items/ORCH-108/12-review.md

@@ -0,0 +1,85 @@
+---
+verdict: APPROVED
+work_item: ORCH-108
+stage: review
+author_agent: reviewer
+status: approved
+created_at: 2026-06-17
+model_used: claude-opus-4-8
+type: review
+work_item_id: ORCH-108
+version: 1
+---
+
+# Review ORCH-108 — FAQ: как использовать STOP для отмены задачи
+
+## Summary
+
+Docs-only задача: создаёт пользовательский FAQ `docs/operations/FAQ_STOP.md` (формат «вопрос →
+ответ»), двусторонние перекрёстные ссылки витрина/обзор ⇄ FAQ ⇄ ADR ORCH-090 и детерминированный
+анти-дрейф тест `tests/test_faq_stop_doc.py`. Поведение STOP — источник истины ORCH-090
+(`adr-0026`) — **не меняется**.
+
+Проверены все 4 оси. **Соответствие ТЗ/AC (1–11)** — полное. **Соответствие ADR** — все решения
+D1–D5 реализованы. **Качество** — тест содержателен, детерминирован, с non-evergreen-самочеком.
+**Документация (приоритетная ось)** — CHANGELOG обновлён, витрина `docs/overview/` обновлена, ADR
+заведён, `src/**` не тронут → нет необновлённой документации. **P0/P1 findings отсутствуют.**
+
+Верификация по ключевым осям:
+- **AC-9 (фактическая корректность) — самая важная для docs-FAQ.** Все 9 утверждений FAQ сверены с
+  кодом (`src/stage_engine.py::cancel_task`, `src/cancel.py`, `src/webhooks/plane.py`,
+  `src/gitea.py`, `src/db.py`) — **каждое CONFIRMED**, противоречий коду нет: graceful SIGTERM-стоп
+  (`launcher.stop_process`); job'ы → терминальный `cancelled`, не реквью'ятся (`claim_next_job`
+  берёт только `queued`); удаление worktree + рабочей ветки с guard `_PROTECTED_BRANCHES={main,
+  master}` (никогда `main`/force-push); docs-артефакты сохраняются; отложенная отмена в критичном
+  окне (`cancel.in_critical_window` → только `queued`-job'ы, running-актор не трогается, finalizer
+  применяет позже); STOP не делает revert влитого; релонч гейтится строго стадией `analysis`
+  (дыра релонча ORCH-090 D6 закрыта); fail-closed no-op (нет `stop` в `_DEFAULT_STATES`) +
+  идемпотентный no-op для терминальной задачи + kill-switch `stop_status_enabled`/`stop_status_repos`.
+- **AC-8 / TR-4 (риск висячего якоря).** Внутренняя ссылка FAQ `…tech-pipeline.md#отмена-stop--cancelled`
+  корректно резолвится в заголовок `## Отмена: STOP → \`cancelled\`` (slug с двойным дефисом от
+  удалённого `→` — совпадает байт-в-байт). Цель ADR-ссылки
+  `docs/work-items/ORCH-090/06-adr/ADR-001-stop-cancel-task.md` существует. Обратные ссылки из
+  `business.md` (Сценарий 6) и `tech-pipeline.md` (Отмена: STOP → `cancelled`) присутствуют.
+- **AC-10 / AC-11.** `git diff origin/main...HEAD`: только `docs/**`, `CHANGELOG.md`,
+  `tests/test_faq_stop_doc.py` (+ scratch `.task-dev.md`); `src/**` / `STAGE_TRANSITIONS` /
+  `QG_CHECKS` / `check_*` / схема БД — не тронуты. `tests/test_faq_stop_doc.py` — 12 passed;
+  `tests/test_system_docs.py` (витрина) — 29 passed.
+
+## Findings
+
+### P0 — Blocker
+- _нет_
+
+### P1 — Must fix
+- _нет_
+
+### P2 — Should fix
+- _нет_
+
+### P3 — Nice-to-have
+- [ ] `.task-dev.md` (scratch-файл dev-трекинга в корне) попал в коммит, обновлён с `ORCH-126` на
+  `ORCH-108`. Это существующий трекируемый файл, к deliverables не относится, рантайм/конвейер не
+  затрагивает — инконсеквентно, фиксации не требует. Отмечено только для полноты.
+
+## Документация
+
+Приоритетная ось пройдена. Это **docs-задача**, `src/**` не изменён → требование «изменил `src/` →
+обнови доку в том же PR» не активируется; при этом всё, что задача обязана обновить, обновлено:
+- **`CHANGELOG.md`** — запись ORCH-108 присутствует (раздел `[Unreleased]`), с инвариантом docs-only
+  и нормативом сопровождения. ✓
+- **Витрина системы `docs/overview/` (ORCH-011)** — `business.md` (Сценарий 6) и `tech-pipeline.md`
+  (Отмена: STOP → `cancelled`) дополнены ссылкой на FAQ; `tests/test_system_docs.py` зелёный
+  (инвариант курируемого каталога витрины не нарушен — FAQ положен в `docs/operations/`, не в
+  `docs/overview/`, см. ADR D1). ✓
+- **ADR** — `docs/work-items/ORCH-108/06-adr/ADR-001-faq-stop-placement-and-anti-drift.md` заведён;
+  сквозной global-ADR обоснованно N/A (локальное docs-only решение, нет нового QG/стадии/компонента/
+  таблицы — критерий `PIPELINE_DOCS.md` §4). ✓
+- **README «Известные ограничения» (ORCH-079)** — ORCH-108 не закрывает ни один из открытых пунктов
+  (Telegram 48h / intra-repo deps / пакетный автоном); STOP уже документирован в README §«Отмена
+  задачи: статус STOP». Обновление README не требуется. ✓
+- **link-first (ADR D4)** — машинные детали (`тумбстон`/`merge-lease`/`_ensure_column`) в FAQ не
+  дублируются, даются ссылками; проверено тестом (`test_faq_links_back_to_overview_and_adr`). ✓
+
+Документация = golden source: обновлена корректно и согласованно. Нет необновлённой документации →
+блокирующего finding'а по этой оси нет.

docs/work-items/ORCH-108/13-test-report.md

@@ -0,0 +1,40 @@
+---
+result: PASS
+work_item: ORCH-108
+stage: testing
+author_agent: test-runner
+status: success
+created_at: 2026-06-17
+model_used: n/a
+exit_code: 0
+smoke: ok
+---
+
+# Test Gate Log (deterministic runner, ORCH-116)
+
+pytest exit-code `0` -> `result: PASS` (smoke: ok).
+
+Вердикт зафиксирован детерминированным test-раннером (ORCH-116), не LLM. PASS/FAIL = exit-код `pytest` + read-only smoke (`/health`, `/status`, `/queue` + блок `serial_gate`).
+
+pytest stdout (tail):
+```
+.................................................................... [ 64%]
+........................................................................ [ 67%]
+........................................................................ [ 71%]
+........................................................................ [ 74%]
+........................................................................ [ 77%]
+........................................................................ [ 80%]
+........................................................................ [ 84%]
+........................................................................ [ 87%]
+........................................................................ [ 90%]
+........................................................................ [ 93%]
+........................................................................ [ 96%]
+...................................................................      [100%]
+=============================== warnings summary ===============================
+src/config.py:8
+  /repos/_wt/orchestrator/feature_ORCH-108-19c40858/src/config.py:8: PydanticDeprecatedSince20: Support for class-based `config` is deprecated, use ConfigDict instead. Deprecated in Pydantic V2.0 to be removed in V3.0. See Pydantic V2 Migration Guide at https://errors.pydantic.dev/2.13/migration/
+    class Settings(BaseSettings):
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+2227 passed, 1 warning in 99.72s (0:01:39)
+```

docs/work-items/ORCH-108/14-deploy-log.md

@@ -0,0 +1,12 @@
+---
+deploy_status: SUCCESS
+work_item: ORCH-108
+hook_exit_code: 0
+deployed_by: deploy-finalizer
+---
+
+# Deploy log — ORCH-036 executable self-deploy
+
+Прод-деплой завершён хост-хуком с exit-code `0` -> `deploy_status: SUCCESS`.
+
+Вердикт зафиксирован детерминированным finalizer'ом (Фаза C), не LLM.

docs/work-items/ORCH-108/15-staging-log.md

@@ -0,0 +1,46 @@
+---
+staging_status: SUCCESS
+work_item: ORCH-108
+stage: deploy-staging
+author_agent: staging-runner
+status: success
+created_at: 2026-06-17
+model_used: n/a
+exit_code: 0
+base_url: http://localhost:8501
+---
+
+# Staging Gate Log (deterministic runner, ORCH-115)
+
+Staging suite exit-code `0` -> `staging_status: SUCCESS`.
+
+Вердикт зафиксирован детерминированным staging-раннером (ORCH-115), не LLM. infra-tolerance (ORCH-061) уже учтена внутри `staging_check.py` — раннер её не пересуживает.
+
+INFRA-WAIVED lines (ORCH-061, copied for observability):
+- INFRA-WAIVED: C9a Branch appears in orchestrator-sandbox, C9b Analyst job enqueued in staging queue (known sandbox-infra; real checks green)
+
+Staging suite stdout (tail):
+```
+ (waiting for analyst job in queue)
+  ·        waiting... (waiting for analyst job in queue)
+  ·        waiting... (waiting for analyst job in queue)
+  ·        waiting... (waiting for analyst job in queue)
+  ·        waiting... (waiting for analyst job in queue)
+  ·        waiting... (waiting for analyst job in queue)
+  ✗ FAIL  C9b Analyst job enqueued in staging queue
+
+[CLEANUP]
+  ·      CLEANUP: no branch to delete
+  ✓ PASS  CLEANUP: deleted Plane issue a38f627e-4ba4-47c3-a19f-3bb939a79a37 (HTTP 204)
+  ·      CLEANUP DB: no task row found for plane_id=a38f627e-4ba4-47c3-a19f-3bb939a79a37
+  ·      CLEANUP DB dedup: no such table: events_dedup
+
+============================================================
+  RESULT: 8/10 checks PASS
+  REAL failed         : none
+  SANDBOX_INFRA failed: ['C9a Branch appears in orchestrator-sandbox', 'C9b Analyst job enqueued in staging queue']
+============================================================
+  ·      tolerance: staging_infra_tolerance_enabled=True
+INFRA-WAIVED: C9a Branch appears in orchestrator-sandbox, C9b Analyst job enqueued in staging queue (known sandbox-infra; real checks green)
+VERDICT: SUCCESS (exit 0) — SUCCESS (infra-waived): ['C9a Branch appears in orchestrator-sandbox', 'C9b Analyst job enqueued in staging queue'] are known sandbox-infra checks; all real checks green
+```

docs/work-items/ORCH-119/00-business-request.md

@@ -0,0 +1,7 @@
+# Business Request: BUG: 00-business-request.md is always TBD, losing source-backed request context
+
+Work Item ID: ORCH-119
+
+## Description
+
+TBD

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

@@ -0,0 +1,151 @@
+---
+work_item: ORCH-119
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-17
+model_used: claude-opus-4-8
+---
+
+# 01 — BRD / Bug-report: ORCH-119 — `00-business-request.md` всегда `TBD`, теряется source-backed контекст запроса
+
+Work Item: **ORCH-119** · Repo: **orchestrator** · Стадия: analysis · Трек: **Bug** (укороченный маршрут, пропуск стадии `architecture`)
+
+> 🐞 **Багфикс-трек (ORCH-019).** Облегчённый пакет (bug-report + обязательный регресс-тест), но
+> все 4 файла analysis (гейт `check_analysis_complete` не меняется). Экономия — в пропуске стадии
+> `architecture`, не в числе файлов.
+>
+> **Эскалация в full-cycle рассмотрена и отклонена.** Дефект — контейнерный data-flow + рендеринг,
+> чинится **точным зеркалированием уже существующего прецедента `tasks.title`** (персист при создании
+> задачи → чтение в `_materialize_deferred_branch`). Нет нового компонента, нового QG, политического
+> решения или визуального артефакта → ADR/макет не требуется. Если разработчик в ходе фикса упрётся в
+> архитектурное решение (напр. иной механизм персиста, влияющий на схему/контракты) — снять трек:
+> `POST /bug-fast-track/escalate?work_item=ORCH-119` и пометить здесь `escalate: full-cycle`.
+
+---
+
+## 1. Бизнес-контекст и проблема
+
+### Симптом (наблюдаемое)
+Для **каждой** созданной задачи файл `docs/work-items/<id>/00-business-request.md` генерируется
+с телом раздела «Description» равным буквальному `TBD`. Реальный текст запроса (описание Plane-issue,
+обогащённое из Plane API) **не попадает** в персистентный артефакт. Пример — сам этот work item:
+
+```
+# Business Request: BUG: 00-business-request.md is always TBD, losing source-backed request context
+Work Item ID: ORCH-119
+## Description
+TBD
+```
+
+### Последствие (бизнес-боль)
+`00-business-request.md` — **точка входа конвейера** и источник для analyst (вход стадии `analysis`,
+см. `PIPELINE_DOCS.md` §2). Когда тело всегда `TBD`:
+- source-backed контекст запроса теряется из durable-артефакта репозитория (остаётся только эфемерно
+  в `task_content` analyst-job'а и в Plane);
+- последующее чтение work item «глазами» (reviewer, человек, ретроспектива, петля уроков) видит пустой
+  бизнес-запрос — невозможно сверить, ту ли задачу решал конвейер;
+- на **self-hosting** (`orchestrator`) задача почти всегда идёт **отложенным срезом ветки** (serial
+  gate, ORCH-088), где контекст теряется безвозвратно (см. §3, причина B).
+
+### Причина симптома (установленный факт, по коду)
+`src/webhooks/plane.py::_create_initial_docs` (строка ~925) **хардкодит** тело:
+```python
+content = f"# Business Request: {name}\n\nWork Item ID: {work_item_id}\n\n## Description\n\nTBD\n"
+```
+Функция принимает только `(repo, branch, work_item_id, name)` — **`description` ей не передаётся**,
+хотя у вызывающего `start_pipeline` оно есть в области видимости и уже используется для analyst-job
+(`task_desc`, строка ~725: `Description:\n{description}`). То есть данные **есть**, но в артефакт не
+доходят.
+
+### Локализация (куда смотреть разработчику) — два пути создания
+
+**Путь A — прямой** (`serial_gate` не применим к репо):
+`start_pipeline` (`src/webhooks/plane.py`) имеет `description` (строки ~518; обогащается из Plane API,
+~539–551) → зовёт `_create_initial_docs(repo, branch, work_item_id, name)` (строка ~710) **без**
+`description`. Достаточно дотянуть аргумент.
+
+**Путь B — отложенный (критичный для self-hosting)** (`serial_gate_applies(repo)` → для `orchestrator`):
+`start_pipeline` **не** создаёт ветку/доки (ORCH-088, анти-stale-base); срез релоцирован в
+`src/agents/launcher.py::_materialize_deferred_branch` (строки ~514–538), который вызывает то же
+`_create_initial_docs`, **располагая только `title`** из строки `tasks` (`description` нигде не
+персистится). Установленный факт схемы: таблица `tasks` **не имеет** колонки `description`; `title`
+персистится через `_ensure_column` (`src/db.py:125`) и читается в `_spawn`/`_materialize_deferred_branch`
+именно так. ⇒ Чтобы путь B рендерил описание, `description` надо **сохранить durable при создании
+задачи** (зеркало `tasks.title`).
+
+### Предусловие истинности данных (установленный факт)
+QG-0 (`_qg0_errors`, `src/webhooks/plane.py:490`) отклоняет создание при `description` короче 20
+символов (строка ~500). ⇒ любая задача, дошедшая до `_create_initial_docs`, **гарантированно имеет
+непустое осмысленное описание** — терять его тем более недопустимо. Защитный fallback на случай
+пустого описания всё равно предусмотреть (NFR-2).
+
+## 2. Объём (scope)
+
+### В объёме
+- Рендер фактического `description` (предпочтительно `description_stripped`, plain-text) в раздел
+  «Description» файла `00-business-request.md` — на **обоих** путях (A прямой, B отложенный).
+- Durable-персист `description` при создании задачи (зеркало `tasks.title`), чтобы путь B имел доступ
+  к нему на момент claim.
+- Защитный fallback при отсутствии/пустом описании (без падения).
+- Обязательный регресс-тест (красный до фикса, зелёный после).
+
+### Вне объёма
+- Изменение `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict-ключей / семантики гейтов.
+- Изменение поведения serial-gate / отложенного среза ветки ORCH-088 (только **дополнить** данными,
+  не менять момент/условие среза).
+- Ретро-генерация `00-business-request.md` для **уже существующих** задач (только новые создания).
+- Переформатирование/обогащение структуры самого `00-business-request.md` сверх вставки описания
+  (заголовки/название источника остаются как есть).
+- Любая запись в Plane (артефакт пишется только в Gitea-ветку, как сейчас).
+
+## 3. Заинтересованные стороны
+- **Заказчик/оператор** — получает читаемый durable бизнес-запрос вместо `TBD`.
+- **Агент analyst и reviewer** — могут сверять решённое с запросом по репозиторию.
+- **Петля уроков / ретроспектива (ORCH-098)** — корректный контекст в артефакте.
+- Приёмку результата выполняет конвейер (reviewer + Quality Gates), не аналитик.
+
+## 4. Бизнес-требования (BR)
+- **BR-1** — Раздел «Description» в `00-business-request.md` содержит **фактический текст запроса**
+  (из Plane-issue, как он используется для analyst-job'а), а не литерал `TBD`, для вновь создаваемых
+  задач.
+- **BR-2** — Поведение одинаково на **обоих** путях создания: прямом (A) и отложенном срезе ветки (B,
+  self-hosting/serial-gate). Путь B — приоритетный сценарий (доминирует на `orchestrator`).
+- **BR-3** — При отсутствующем/пустом описании артефакт создаётся с **явным безопасным fallback**-
+  маркером (напр. «описание отсутствует в источнике»), без падения создания задачи.
+- **BR-4** — Сохранён состав/имена артефактов: создаётся ровно `00-business-request.md` по тому же
+  пути; downstream-конвейер (analyst и далее) не затронут.
+
+## 5. Нефункциональные требования (NFR)
+- **NFR-1 (обратная совместимость / never-break)** — изменение аддитивно: создание задачи **никогда**
+  не должно падать из-за нового рендера/персиста. Любая ошибка обогащения → деградация на безопасное
+  значение (fallback-маркер), а не отказ создания. Идемпотентность `_create_initial_docs` (422 = уже
+  существует → no-op) сохранена.
+- **NFR-2 (целостность данных)** — описание рендерится **как есть** (plain-text `description_stripped`),
+  без обрезки/искажения; многострочный текст сохраняется. `00-business-request.md` — информационный
+  док (гейтом не парсится), поэтому markdown-спецсимволы в описании безопасны для гейтов.
+- **NFR-3 (инварианты ORCH-088)** — момент и условие отложенного среза ветки не меняются; описание
+  лишь дополнительно переносится через durable-хранилище (зеркало `tasks.title`), анти-stale-base
+  логика цела.
+- **NFR-4 (self-hosting-безопасность)** — фикс не деплоит/не рестартит прод, не трогает `main`, не
+  добавляет сетевых вызовов в горячий `claim_next_job`.
+
+## 6. Допущения и ограничения
+- `description`/`description_stripped` доступны в `start_pipeline` и достаточны как источник (уже
+  используются для analyst-job). Plane-обогащение (ORCH «name_missing/desc_missing» блок) остаётся
+  единственным источником описания — новых сетевых обращений не вводим.
+- QG-0 гарантирует ≥20 символов описания для прошедших задач (см. §1) — нормальный путь всегда имеет
+  реальный текст.
+- Персист описания следует **установленному прецеденту `tasks.title`** (аддитивная колонка через
+  `_ensure_column`); это не новое архитектурное решение.
+
+## 7. Критерии успеха
+Новые задачи получают `00-business-request.md` с реальным описанием на обоих путях; обязательный
+регресс-тест красный до фикса и зелёный после; полный `pytest tests/ -q` зелёный. Детальные PASS/FAIL
+— `03-acceptance-criteria.md`.
+
+## 8. Риски
+- Путь B забыт (чинят только прямой путь A) → на self-hosting баг остаётся. Митигируется обязательным
+  integration-тестом пути B (TC-03).
+- Регресс схемы/создания задачи при добавлении персиста → митигируется аддитивным `_ensure_column` и
+  тестом обратной совместимости (TC-05). Детальные тех-риски архитектором не выпускаются (bug-track).

docs/work-items/ORCH-119/02-trz.md

@@ -0,0 +1,86 @@
+---
+work_item: ORCH-119
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-17
+model_used: claude-opus-4-8
+---
+
+# 02 — ТЗ (TRZ): ORCH-119 — source-backed генерация `00-business-request.md`
+
+Work Item: **ORCH-119** · Repo: **orchestrator** · Стадия: analysis · Трек: **Bug**
+
+> Bug-track: стадия `architecture` пропускается, поэтому ТЗ конкретизирует затрагиваемые модули и
+> требование к данным. ТЗ описывает **что должно измениться и где**; точная форма реализации (имена
+> символов, сигнатуры) — за разработчиком, в рамках указанного прецедента `tasks.title`.
+
+## 1. Сводка изменения
+Source-backed `description` (текст запроса из Plane-issue) должен попадать в раздел «Description»
+файла `00-business-request.md` вместо хардкода `TBD`. Для этого: (1) `description` рендерится в тело
+артефакта; (2) `description` **персистится при создании задачи** (зеркало `tasks.title`), чтобы
+отложенный путь среза ветки (ORCH-088, доминирует на self-hosting) имел к нему доступ на момент claim.
+Изменение аддитивно, never-break, fail-safe.
+
+## 2. Задействованные модули / пути
+| Путь | Действие |
+|------|----------|
+| `src/webhooks/plane.py` | изменить — `_create_initial_docs`: принять `description`, рендерить его в тело вместо `TBD`; рекомендуется выделить чистый рендер-хелпер (напр. `_render_business_request(work_item_id, name, description) -> str`) для unit-тестируемости без сети |
+| `src/webhooks/plane.py` | изменить — `start_pipeline`: (а) прямой путь — передать `description` в `_create_initial_docs` (строка ~710); (б) персистить `description` при создании задачи (рядом со стампом `title`) |
+| `src/agents/launcher.py` | изменить — `_materialize_deferred_branch`: прочитать персистнутое `description` из строки `tasks` и передать в `_create_initial_docs` (зеркало того, как уже читается/используется `title`) |
+| `src/db.py` | изменить — аддитивная колонка `tasks.description` через `_ensure_column` (паттерн `tasks.title`, строка ~125); хелпер чтения/записи при необходимости; **не менять** базовый `CREATE TABLE tasks` |
+| `tests/test_orch119_business_request.py` | создать — регресс + edge-кейсы (см. `04-test-plan.yaml`) |
+| `CHANGELOG.md` | изменить — запись о фиксе (правило сопровождения) |
+
+## 3. Функциональные требования
+
+### FR-1 — Рендер описания в артефакт (BR-1)
+Тело раздела «Description» в `00-business-request.md` = фактический `description` (предпочтительно
+`description_stripped`, plain-text), без обрезки/искажения, многострочный текст сохраняется. Заголовок
+(`# Business Request: {name}`) и `Work Item ID` — без изменений.
+
+### FR-2 — Прямой путь (BR-2, путь A)
+`start_pipeline` при `serial_gate` НЕ применим → передаёт `description` в `_create_initial_docs`;
+артефакт создаётся с реальным описанием в одном вызове.
+
+### FR-3 — Отложенный путь / персист (BR-2, путь B — критичный)
+`description` персистится durable при создании задачи (зеркало `tasks.title`).
+`_materialize_deferred_branch` читает его из строки `tasks` и передаёт в `_create_initial_docs`, так
+что артефакт, материализованный на момент claim analyst-job, содержит реальное описание. Момент/условие
+отложенного среза (ORCH-088) **не меняются** — только источник данных дополняется (NFR-3).
+
+### FR-4 — Fallback и устойчивость (BR-3, NFR-1)
+Пустое/отсутствующее/нечитаемое `description` → явный безопасный маркер (напр.
+`_(описание отсутствует в источнике)_`), **без падения** создания задачи. Любая ошибка рендера/чтения
+персиста → деградация на fallback-маркер, не отказ. Идемпотентность сохранена: повторная
+материализация (Gitea 422 = файл уже существует) → no-op, ранее записанное тело не перезаписывается.
+
+## 4. Изменения API
+Нет. Эндпоинты не добавляются и не меняются. Запись артефакта остаётся в Gitea-ветку через
+существующий `contents` API; в Plane ничего не пишется.
+
+## 5. Изменения схемы БД
+Аддитивная колонка **`tasks.description TEXT`** через `_ensure_column` (идемпотентный ALTER, no-op на
+существующей таблице — safe на боевой БД), строго по прецеденту `tasks.title`. Базовый
+`CREATE TABLE tasks` не трогается. Индексы не требуются. Для уже существующих задач колонка `NULL`
+(ретро-генерация — вне объёма).
+
+> Допустимая эквивалентная реализация (на усмотрение разработчика): переиспользовать уже доступный
+> в `_spawn`/`_materialize_deferred_branch` источник данных, если он durable до момента claim. Если
+> такой надёжно нет — канон именно колонка `tasks.description` (как `tasks.title`). Решение не должно
+> вводить сетевой вызов в горячий путь claim (NFR-4).
+
+## 6. Требования к новым/изменённым QG checks
+Нет. `00-business-request.md` — информационный документ (гейтом не парсится, `PIPELINE_DOCS.md` §2–§3).
+`STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict-ключи — байт-в-байт не трогаются.
+
+## 7. Совместимость / регресс
+- **Обратная совместимость:** аддитивная колонка + аддитивный аргумент с дефолтом; существующие задачи
+  и enduro-trails не затронуты (для них тоже просто рендерится их описание — улучшение, не регресс).
+- **Kill-switch:** отдельный флаг не требуется — изменение это исправление дефекта (улучшение
+  «всегда»), не рискованная фича; безопасность обеспечивается fail-safe fallback и never-break-контрактом.
+- **Обратимость:** revert PR полностью возвращает прежнее поведение (колонка остаётся, инертна).
+- **Self-hosting:** не деплоит/не рестартит прод, не трогает `main`, без новых сетевых вызовов в
+  `claim_next_job` (NFR-4). Анти-stale-base инвариант ORCH-088 цел (NFR-3) — перед правкой
+  `_materialize_deferred_branch`/отложенного среза свериться с `docs/work-items/ORCH-088/06-adr/`
+  (TRACEABILITY).

docs/work-items/ORCH-119/03-acceptance-criteria.md

@@ -0,0 +1,109 @@
+---
+work_item: ORCH-119
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-17
+model_used: claude-opus-4-8
+---
+
+# 03 — Критерии приёмки: ORCH-119 — source-backed `00-business-request.md`
+
+Work Item: **ORCH-119** · Repo: **orchestrator** · Стадия: analysis · Трек: **Bug**
+
+Формат: каждый критерий — **PASS** (что должно быть истинно для приёмки) и **FAIL** (что считается
+провалом). Reviewer/тесты проверяют буквально по файлам репозитория.
+
+---
+
+## AC-1 — Реальное описание в артефакте вместо `TBD`
+
+**Условие:** при создании задачи с непустым описанием раздел «Description» файла
+`00-business-request.md` содержит фактический текст запроса.
+- **PASS:** тело раздела «Description» равно переданному `description` (plain-text); подстрока с
+  реальным текстом присутствует; литерал `TBD` как ВСЁ тело раздела отсутствует.
+- **FAIL:** раздел «Description» = `TBD` (или иной плейсхолдер) при наличии непустого описания на входе.
+
+---
+
+## AC-2 — Прямой путь создания (путь A)
+
+**Условие:** когда `serial_gate` не применим, `start_pipeline` передаёт `description` в
+`_create_initial_docs`.
+- **PASS:** артефакт, созданный прямым путём, содержит реальное описание (см. AC-1).
+- **FAIL:** на прямом пути `description` не доходит до артефакта (остаётся `TBD`).
+
+---
+
+## AC-3 — Отложенный путь / self-hosting (путь B, критичный)
+
+**Условие:** когда `serial_gate_applies(repo)` (напр. `orchestrator`), описание персистится при
+создании задачи и рендерится при материализации ветки на момент claim
+(`launcher._materialize_deferred_branch`).
+- **PASS:** артефакт, материализованный отложенным путём, содержит реальное описание; описание
+  durable-доступно из строки `tasks` (не теряется между созданием задачи и claim).
+- **FAIL:** на отложенном пути описание утрачено → артефакт = `TBD`; либо описание нигде не
+  персистится до момента claim.
+
+---
+
+## AC-4 — Безопасный fallback при пустом описании
+
+**Условие:** описание отсутствует/пустое/нечитаемо.
+- **PASS:** артефакт создаётся с явным безопасным fallback-маркером (не «голый» `TBD`-баг), создание
+  задачи не падает.
+- **FAIL:** создание задачи падает/бросает исключение, либо тихо теряет контекст без маркера.
+
+---
+
+## AC-5 — Никаких изменений гейтов / схемы сверх аддитивной колонки
+
+**Условие:** правка не трогает машинерию конвейера.
+- **PASS:** `STAGE_TRANSITIONS`, реестр `QG_CHECKS`, имена/семантика `check_*`, machine-verdict-ключи
+  — байт-в-байт прежние; единственное изменение схемы — аддитивная `tasks.description` (или
+  эквивалент без сетевого вызова в claim); базовый `CREATE TABLE tasks` не тронут.
+- **FAIL:** изменены гейты/переходы/вердикт-ключи; неаддитивная миграция; сетевой вызов добавлен в
+  `claim_next_job`.
+
+---
+
+## AC-6 — Идемпотентность и обратная совместимость
+
+**Условие:** повторная материализация и существующие задачи.
+- **PASS:** повторный вызов (`_create_initial_docs`, Gitea 422) — no-op, не перезаписывает тело;
+  `_ensure_column` идемпотентен (no-op при существующей колонке); enduro-trails и прочие репо не
+  затронуты негативно.
+- **FAIL:** повторная материализация затирает/дублирует артефакт; миграция падает на боевой БД;
+  регресс для других репо.
+
+---
+
+## AC-7 — Обязательный регресс-тест (red→green) и зелёный полный прогон
+
+**Условие:** дефект зафиксирован тестом.
+- **PASS:** `tests/test_orch119_business_request.py::TC-01` падает на коде ДО фикса (доказывает баг) и
+  проходит ПОСЛЕ; полный `pytest tests/ -q` зелёный.
+- **FAIL:** регресс-теста нет, либо он зелёный и до фикса (ничего не доказывает), либо полный прогон
+  красный.
+
+---
+
+## AC-8 — Сопровождение
+
+**Условие:** документация/история обновлены в том же PR.
+- **PASS:** `CHANGELOG.md` содержит запись о фиксе ORCH-119.
+- **FAIL:** изменён функционал без обновления `CHANGELOG.md`.
+
+---
+
+## Сводная матрица AC ↔ FR/BR
+| AC | Покрывает |
+|----|-----------|
+| AC-1 | BR-1 / FR-1 |
+| AC-2 | BR-2 / FR-2 |
+| AC-3 | BR-2 / FR-3 / NFR-3 |
+| AC-4 | BR-3 / FR-4 / NFR-1 |
+| AC-5 | BR-4 / NFR-4 |
+| AC-6 | NFR-1 / FR-4 |
+| AC-7 | BR-1..BR-3 (доказательство) |
+| AC-8 | правило сопровождения |

docs/work-items/ORCH-119/04-test-plan.yaml

@@ -0,0 +1,64 @@
+work_item: ORCH-119
+stage: analysis
+author_agent: analyst
+status: ready-for-review
+created_at: 2026-06-17
+model_used: claude-opus-4-8
+title: "Source-backed генерация 00-business-request.md (фикс хардкода TBD)"
+framework: pytest
+scope: >
+  Покрывается: рендер фактического description в 00-business-request.md вместо литерала TBD на обоих
+  путях создания (прямой A и отложенный срез ветки B / self-hosting ORCH-088), durable-персист
+  description (зеркало tasks.title), безопасный fallback при пустом описании, аддитивность схемы и
+  обратная совместимость. ВНЕ покрытия: реальные сетевые вызовы Gitea/Plane (мокаются), ретро-генерация
+  артефактов для уже существующих задач.
+notes: >
+  TC-01 — ОБЯЗАТЕЛЬНЫЙ регресс-тест: красный на коде ДО фикса (доказывает баг хардкода TBD), зелёный
+  ПОСЛЕ. Сетевые вызовы (_create_gitea_branch / _create_initial_docs httpx, Plane API) мокаются —
+  тесты без сети/прода. Рекомендуется тестировать чистый рендер-хелпер (_render_business_request) на
+  уровне unit, а пути A/B — на уровне integration с моками httpx и временной SQLite-БД. Полный регресс
+  pytest tests/ -q должен оставаться зелёным. Перед правкой отложенного среза ветки свериться с
+  docs/work-items/ORCH-088/06-adr/ (анти-stale-base инвариант, TRACEABILITY).
+
+tests:
+  - id: TC-01
+    type: unit
+    description: "ОБЯЗАТЕЛЬНЫЙ РЕГРЕСС. Рендер 00-business-request.md при непустом description содержит фактический текст запроса в разделе 'Description' и НЕ равен литералу TBD. Красный до фикса (хардкод TBD), зелёный после."
+    module: tests/test_orch119_business_request.py
+    expected: PASS
+
+  - id: TC-02
+    type: unit
+    description: "Fallback: при пустом/whitespace/None description рендер даёт явный безопасный маркер (напр. 'описание отсутствует в источнике'), функция не бросает исключение."
+    module: tests/test_orch119_business_request.py
+    expected: PASS
+
+  - id: TC-03
+    type: integration
+    description: "Путь B (отложенный, self-hosting): description персистнут при создании задачи и доступен из строки tasks; launcher._materialize_deferred_branch рендерит реальное описание в артефакт (мок httpx; description не теряется между созданием и claim)."
+    module: tests/test_orch119_business_request.py
+    expected: PASS
+
+  - id: TC-04
+    type: integration
+    description: "Путь A (прямой, serial_gate не применим): start_pipeline передаёт description в _create_initial_docs; артефакт содержит реальное описание (мок httpx, перехват записанного content)."
+    module: tests/test_orch119_business_request.py
+    expected: PASS
+
+  - id: TC-05
+    type: integration
+    description: "Обратная совместимость схемы: init_db на пустой БД и на БД со старой таблицей tasks (без колонки description) проходит; _ensure_column идемпотентен (повторный init_db — no-op); создание задачи не падает."
+    module: tests/test_orch119_business_request.py
+    expected: PASS
+
+  - id: TC-06
+    type: unit
+    description: "Целостность данных: многострочное описание со спецсимволами markdown рендерится без обрезки/искажения; идемпотентность — повторная материализация (Gitea 422) не перезаписывает уже записанное тело."
+    module: tests/test_orch119_business_request.py
+    expected: PASS
+
+  - id: TC-07
+    type: unit
+    description: "Анти-регресс гейтов: STAGE_TRANSITIONS / реестр QG_CHECKS / имена check_* импортируются без изменений (00-business-request.md остаётся информационным, не гейтится)."
+    module: tests/test_orch119_business_request.py
+    expected: PASS

docs/work-items/ORCH-119/06-adr/ADR-001-source-backed-business-request-doc.md

@@ -0,0 +1,162 @@
+---
+work_item: ORCH-119
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-17
+model_used: claude-opus-4-8
+---
+
+# ADR-001: Durable-персист `description` для source-backed `00-business-request.md`
+
+Work Item: **ORCH-119** — `00-business-request.md` всегда `TBD`, теряется source-backed контекст запроса
+Стадия: **architecture**
+Сквозная регистрация: **N/A, локальное решение задачи** (аддитивная скалярная колонка по
+прецеденту `tasks.title`; не новый QG / стадия / компонент / смена БД-движка → сквозной
+`docs/architecture/adr/adr-NNNN-*` не заводится).
+
+> **Примечание по треку (Bug, ORCH-019).** Задача классифицирована как Bug и по BRD должна была
+> идти укороченным маршрутом (пропуск `architecture`). Фактически задача **дошла до стадии
+> `architecture`** (routing-override ORCH-019 не сработал — нет метки `Bug` в Plane / выключен
+> `bug_fast_track`), а exit-гейт `check_architecture_done` (`src/qg/checks.py:62`) требует ≥1 файла
+> в `06-adr/` или `07-infra-requirements.md`. Поэтому архитектурный выход выпускается штатно. ADR
+> намеренно компактный: он фиксирует **локальное** решение по data-flow и аддитивной схеме, без
+> сквозных последствий.
+
+## Статус
+Proposed
+
+## Контекст
+
+`src/webhooks/plane.py::_create_initial_docs` (`src/webhooks/plane.py:925`) **хардкодит** тело
+раздела «Description»:
+
+```python
+content = f"# Business Request: {name}\n\nWork Item ID: {work_item_id}\n\n## Description\n\nTBD\n"
+```
+
+Сигнатура `_create_initial_docs(repo, branch, work_item_id, name)` (`:917`) **не принимает**
+`description`, хотя у вызывающего `start_pipeline` оно есть в области видимости (`:518`, обогащается
+из Plane API `:540–551`) и уже используется для analyst-job (`task_desc`, `:723–725`). Данные есть —
+в durable-артефакт не доходят.
+
+Есть **два** пути создания (сверено по коду):
+
+- **Путь A (прямой)** — `serial_gate` не применим к репо: `start_pipeline` сам зовёт
+  `_create_initial_docs(repo, branch, work_item_id, name)` (`src/webhooks/plane.py:710`). `description`
+  здесь в области видимости — достаточно дотянуть аргумент.
+- **Путь B (отложенный, доминирует на self-hosting `orchestrator`)** — `serial_gate_applies(repo)`
+  (ORCH-088, анти-stale-base): `start_pipeline` **НЕ** режет ветку/доки (`:697–717`); срез
+  релоцирован на claim analyst-job в `src/agents/launcher.py::_materialize_deferred_branch`
+  (`:514–538`), который располагает только `title` из строки `tasks`
+  (`SELECT branch, work_item_id, title FROM tasks`, `:561`). **`description` в таблице `tasks` не
+  персистится** (базовый `CREATE TABLE tasks`, `src/db.py:31–42`, его не содержит) → путь B физически
+  не имеет доступа к описанию на момент claim.
+
+Предусловие истинности данных: QG-0 (`_qg0_errors`, `src/webhooks/plane.py:490–500`) отклоняет
+создание при `description` короче 20 символов ⇒ нормальный путь всегда имеет осмысленный текст; терять
+его недопустимо.
+
+Прямой прецедент: `tasks.title` — аддитивная колонка (`_ensure_column(conn,"tasks","title","TEXT")`,
+`src/db.py:125`), записываемая атомарно при создании задачи (`create_task_atomic`, `src/db.py:678–683`)
+и читаемая в `_spawn`/`_materialize_deferred_branch`. ORCH-119 решается **точным зеркалированием**
+этого прецедента для `description`.
+
+## Решение
+
+### Сводка
+Персистить `description` durable при создании задачи как **аддитивную колонку `tasks.description TEXT`**
+(зеркало `tasks.title`), записываемую **внутри того же атомарного INSERT** `create_task_atomic`
+(ORCH-053). На обоих путях создания тело `00-business-request.md` рендерится из фактического описания
+через выделенный чистый хелпер с fail-safe fallback. `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` /
+machine-verdict-ключи / базовый `CREATE TABLE tasks` — не трогаются.
+
+### D1 — Где персистить описание (ключевое решение)
+**Решение: аддитивная колонка `tasks.description TEXT` через `_ensure_column`, записываемая атомарно
+в `create_task_atomic`.**
+
+Путь B (отложенный срез) читает данные задачи из строки `tasks` на момент claim — единственное
+durable-место, доступное и пути A, и пути B без сети. Колонка добавляется идемпотентным
+`_ensure_column(conn, "tasks", "description", "TEXT")` рядом с `tasks.title` (`src/db.py:125`); базовый
+`CREATE TABLE tasks` не меняется (no-op на боевой общей БД, restart-safe). Запись `description`
+**встраивается в существующий INSERT** `create_task_atomic` (расширяется список колонок/значений,
+`src/db.py:678–683`), а не отдельным `UPDATE` — чтобы персист был атомарен и race-safe относительно
+анти-dup-claim ORCH-053 (никакого окна, в котором задача создана, но описание ещё не записано).
+Сигнатура `create_task_atomic` расширяется аддитивным параметром `description` с дефолтом → обратная
+совместимость прочих вызывающих (напр. F-2 reconciler) сохранена. Привязка: FR-3, AC-3, NFR-3, NFR-4.
+
+### D2 — Чистый рендер-хелпер + проброс на обоих путях
+**Решение: выделить чистую функцию рендера тела и пробросить `description` в `_create_initial_docs`
+на обоих путях.**
+
+`_create_initial_docs` принимает аддитивный аргумент `description` и делегирует формирование тела
+чистому хелперу (напр. `_render_business_request(work_item_id, name, description) -> str`,
+unit-тестируемому без сети — TC-01/TC-02/TC-06). Заголовок (`# Business Request: {name}`) и
+`Work Item ID` — без изменений; меняется только тело раздела «Description».
+- **Путь A:** `start_pipeline` передаёт `description` в `_create_initial_docs` (`:710`).
+- **Путь B:** `_spawn` расширяет `SELECT` до `..., description` (`src/agents/launcher.py:561`),
+  `_materialize_deferred_branch` принимает `description` 5-м аргументом (`:514–516`, `:582–584`) и
+  передаёт в `_create_initial_docs` (`:538`).
+Привязка: FR-1, FR-2, AC-1, AC-2.
+
+### D3 — Fail-safe fallback и идемпотентность (never-break)
+**Решение: пустое/None/нечитаемое описание → явный безопасный маркер; любая ошибка рендера/чтения →
+деградация на маркер, не отказ создания.**
+
+При `description` пустом/whitespace/`None` (включая `NULL` у исторических задач, для которых колонка
+не заполнялась) хелпер возвращает явный маркер (напр. `_(описание отсутствует в источнике)_`), а не
+голый `TBD`. Создание задачи **никогда** не падает из-за рендера/персиста — все обогащения изолированы
+(`try/except` → fallback). Идемпотентность сохранена: `_create_initial_docs` на Gitea-`422`
+(файл существует) → no-op, ранее записанное тело не перезаписывается (повторная материализация после
+рестарта/реклейма безопасна). Привязка: FR-4, AC-4, AC-6, NFR-1.
+
+### D4 — Что НЕ трогаем (инварианты)
+- **ORCH-088 (анти-stale-base):** момент и условие отложенного среза ветки не меняются — только
+  источник данных дополняется durable-колонкой; `_materialize_deferred_branch` по-прежнему режет ветку
+  из свежего `origin/main` на claim. Перед правкой блока ORCH-088 свериться с
+  `docs/work-items/ORCH-088/06-adr/ADR-001-serial-gate.md` (TRACEABILITY). NFR-3.
+- **ORCH-053 (атомарный анти-dup-claim):** запись `description` — в том же INSERT под
+  `_CREATE_TASK_LOCK`; семантика `(row, created)` не меняется.
+- **Гейты:** `00-business-request.md` — информационный док (гейтом не парсится, `PIPELINE_DOCS.md`
+  §2–§3); `STAGE_TRANSITIONS` / реестр `QG_CHECKS` / имена/семантика `check_*` / machine-verdict —
+  байт-в-байт. AC-5.
+- **Без kill-switch:** это исправление дефекта (улучшение «всегда»), не рискованная фича; безопасность
+  обеспечивается fail-safe fallback и never-break-контрактом (TRZ §7). Обратимость — revert PR
+  (колонка остаётся инертной).
+
+## Альтернативы
+- **Чинить только путь A (без персиста)** — отвергнуто: путь B (self-hosting `orchestrator`, доминирует)
+  останется `TBD`; нарушает BR-2 (приоритетный сценарий).
+- **Хранить описание в `task_content` / payload job'а** — отвергнуто: эфемерно, привязано к жизненному
+  циклу job'а; `_materialize_deferred_branch` читает данные из строки `tasks`, а не из job'а; нет
+  durable-доступа на момент claim.
+- **Re-fetch описания из Plane API в `_materialize_deferred_branch`** — отвергнуто: добавляет сетевой
+  вызов рядом с горячим путём claim (нарушает NFR-4) и вводит зависимость материализации от
+  доступности Plane; ORCH-088 сознательно сделал claim детерминированным.
+- **Отдельная таблица `task_metadata`** — отвергнуто: оверинжиниринг; прецедент `tasks.title` уже
+  канонизирует аддитивную скалярную колонку per-task.
+- **Эскалация в full-cycle (`arch:major-change` / `back-to:analysis`)** — отвергнуто: решение
+  аддитивно, по установленному прецеденту, без нового компонента/QG/стадии/смены БД-движка и без
+  нарушения принципов; ТЗ удовлетворяется штатно.
+
+## Последствия
+- **+** Durable source-backed контекст в `00-business-request.md` на обоих путях; зеркало проверенного
+  прецедента (низкий риск).
+- **+** Ноль изменений машинерии конвейера (гейты/переходы/вердикты/базовая схема) → ноль риска
+  регресса конвейера; enduro-trails не затронут (для него тоже просто рендерится его описание).
+- **−** Схема общей прод-БД растёт на одну колонку → митигировано аддитивным `_ensure_column` (no-op
+  при наличии, без переписывания базового `CREATE TABLE`), обратная совместимость (`NULL` у
+  существующих строк, fallback-маркер при рендере).
+- **−** Уже созданные задачи не ретро-генерируются (вне объёма, принято; колонка `NULL` → fallback).
+- **Откат:** revert PR полностью возвращает прежнее поведение; аддитивная колонка остаётся инертной
+  (без обязательной down-миграции на общей БД).
+
+## Ссылки
+- BRD: `docs/work-items/ORCH-119/01-brd.md`
+- TRZ: `docs/work-items/ORCH-119/02-trz.md`
+- Acceptance: `docs/work-items/ORCH-119/03-acceptance-criteria.md`
+- Data-requirements: `docs/work-items/ORCH-119/08-data-requirements.md`
+- Tech-risks: `docs/work-items/ORCH-119/10-tech-risks.md`
+- Сверено по коду: `src/webhooks/plane.py:482,490,518,710,917,925` · `src/agents/launcher.py:514,531,538,561,582` · `src/db.py:31,125,647,678` · `src/qg/checks.py:62`
+- Инвариант ORCH-088: `docs/work-items/ORCH-088/06-adr/ADR-001-serial-gate.md`
+- Стандарт документов / ADR-naming: `docs/_standards/PIPELINE_DOCS.md` §4

docs/work-items/ORCH-119/08-data-requirements.md

@@ -0,0 +1,49 @@
+---
+work_item: ORCH-119
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-17
+model_used: claude-opus-4-8
+---
+
+# 08 — Требования к данным: ORCH-119 — durable-персист `description` задачи
+
+Work Item: **ORCH-119** · Repo: **orchestrator** · Стадия: architecture
+
+> When-applicable / информационный (гейтом не парсится). Применимо: фикс требует durable-хранения
+> `description` в строке `tasks` для пути B (отложенный срез ветки, ORCH-088).
+
+## Изменения схемы БД
+- **Новая колонка `tasks.description TEXT`** — добавляется идемпотентным
+  `_ensure_column(conn, "tasks", "description", "TEXT")` (`src/db.py`, рядом с `tasks.title`,
+  `src/db.py:125`). Прецедент 1:1 — `tasks.title` / `tasks.track` / `tasks.cancelled_at`.
+- Базовый `CREATE TABLE tasks` (`src/db.py:31–42`) **не трогается**.
+- Индексы **не требуются** (колонка не участвует в выборках/JOIN; читается по PK `tasks.id`).
+- `NULL` по умолчанию; для уже существующих задач остаётся `NULL` (ретро-генерация вне объёма).
+
+## Новые/изменённые сущности
+- **`tasks.description`** — plain-text описание запроса (предпочтительно `description_stripped`
+  Plane-issue), записывается **при создании задачи** внутри атомарного INSERT
+  `create_task_atomic` (`src/db.py:678–683`; список колонок/значений расширяется, параметр
+  `description` аддитивен с дефолтом). Читается на пути B в `_spawn`
+  (`SELECT ..., description FROM tasks`, `src/agents/launcher.py:561`) и передаётся в
+  `_materialize_deferred_branch` → `_create_initial_docs`.
+- Инвариант данных: значение пишется **как есть**, без обрезки/искажения; многострочный текст и
+  markdown-спецсимволы сохраняются (`00-business-request.md` гейтом не парсится — спецсимволы
+  безопасны, NFR-2). Пустое/`NULL` → рендер деградирует на fallback-маркер (ADR-001 D3), не на
+  отказ.
+
+## Совместимость данных / миграции
+- **Аддитивность:** только `ADD COLUMN` через `_ensure_column`; существующая боевая ОБЩАЯ БД и
+  enduro-trails не затронуты (для них `description` тоже просто рендерится — улучшение, не регресс).
+- **Идемпотентность:** `_ensure_column` — no-op при наличии колонки; повторный `init_db` безопасен
+  (TC-05). `_create_initial_docs` на Gitea-`422` — no-op (тело не перезаписывается, TC-06).
+- **Restart-safe / атомарность:** запись `description` — в том же INSERT под `_CREATE_TASK_LOCK`
+  (ORCH-053), без окна «задача создана, описание отсутствует»; реклейм/материализация после
+  рестарта безопасны.
+- **Down-миграция:** не требуется — revert PR оставляет колонку инертной (без обязательного DROP на
+  общей прод-БД).
+- **Влияние на общую прод-БД (self-hosting):** одна аддитивная колонка, без рестарта прода в рамках
+  схемы (применяется на следующем `init_db`); без новых сетевых вызовов в горячем `claim_next_job`
+  (NFR-4).

docs/work-items/ORCH-119/10-tech-risks.md

@@ -0,0 +1,37 @@
+---
+work_item: ORCH-119
+stage: architecture
+author_agent: architect
+status: proposed
+created_at: 2026-06-17
+model_used: claude-opus-4-8
+---
+
+# 10 — Технические риски: ORCH-119 — source-backed `00-business-request.md`
+
+Work Item: **ORCH-119** · Repo: **orchestrator** · Стадия: architecture
+
+> Информационный (гейтом не парсится). Перечисляет риски реализации и их митигейшн.
+
+## Реестр рисков
+
+| ID | Риск | Вер. | Влия. | Митигейшн |
+|----|------|------|-------|-----------|
+| TR-1 | Чинят только прямой путь A, путь B (отложенный срез, self-hosting) забыт → на `orchestrator` баг остаётся (`TBD`) | Сред. | Выс. | Обязательный integration-тест пути B (TC-03): персист в `tasks` + рендер в `_materialize_deferred_branch`; ADR-001 D1/D2 явно фиксирует оба пути |
+| TR-2 | Регресс схемы/создания задачи при добавлении персиста на ОБЩЕЙ прод-БД | Низ. | Выс. | Аддитивный идемпотентный `_ensure_column` (no-op при наличии), базовый `CREATE TABLE` не трогается; тест обратной совместимости (TC-05) |
+| TR-3 | Падение создания задачи из-за рендера/чтения описания (нарушение never-break) | Низ. | Выс. | Fail-safe fallback-маркер + изоляция обогащения (`try/except`); создание задачи не зависит от рендера (ADR-001 D3, TC-02) |
+| TR-4 | Гонка ORCH-053: окно «задача создана, описание ещё не записано» при отдельном `UPDATE` | Низ. | Сред. | Запись `description` встроена в тот же атомарный INSERT `create_task_atomic` под `_CREATE_TASK_LOCK`, отдельного `UPDATE` нет (ADR-001 D1) |
+| TR-5 | Повторная материализация (рестарт/реклейм) перезаписывает/дублирует тело артефакта | Низ. | Сред. | Идемпотентность `_create_initial_docs` (Gitea `422` → no-op), тело не перезаписывается (TC-06) |
+| TR-6 | Нарушение анти-stale-base инварианта ORCH-088 при правке отложенного среза | Низ. | Выс. | Момент/условие среза НЕ меняются — только источник данных дополняется durable-колонкой; сверка с `docs/work-items/ORCH-088/06-adr/` перед правкой (ADR-001 D4, NFR-3) |
+| TR-7 | Случайная правка `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict | Низ. | Выс. | `00-business-request.md` информационный (не гейтится); анти-регресс-тест импорта гейтов без изменений (TC-07, AC-5) |
+| TR-8 | Markdown-спецсимволы/многострочность описания искажают артефакт | Низ. | Низ. | Рендер plain-text «как есть» без обрезки; артефакт гейтом не парсится → спецсимволы безопасны (NFR-2, TC-06) |
+
+## Сводный вывод
+Доминирующий класс — **операционные риски реализации** (полнота покрытия обоих путей + сохранение
+never-break/идемпотентности/инвариантов ORCH-088/ORCH-053), не архитектурные. Все они закрываются
+обязательными регресс- и edge-тестами (`04-test-plan.yaml` TC-01…TC-07) и точным следованием
+прецеденту `tasks.title`. Эскалация **не требуется**: решение аддитивно, обратимо (revert PR),
+без нового компонента/QG/стадии/смены БД-движка → `arch:major-change` не выставляется, возврат в
+анализ (`back-to:analysis`) не нужен. Остаточный риск для прод-конвейера (self-hosting) — **низкий**:
+фикс не деплоит/не рестартит прод, не трогает `main`, не добавляет сетевых вызовов в горячий
+`claim_next_job` (NFR-4).

docs/work-items/ORCH-119/12-review.md

@@ -0,0 +1,151 @@
+---
+verdict: APPROVED
+work_item: ORCH-119
+stage: review
+author_agent: reviewer
+status: approved
+created_at: 2026-06-17
+model_used: claude-opus-4-8
+type: review
+work_item_id: ORCH-119
+version: 3
+---
+
+# Review ORCH-119 — source-backed `00-business-request.md` вместо хардкода `TBD`
+
+## Summary
+
+Узко-скоупленный багфикс (Bug-трек). Раздел «Description» файла `00-business-request.md`
+теперь несёт **фактический текст запроса** из Plane-issue вместо литерала `TBD` — на **обоих**
+путях создания: прямой (путь A) и **отложенный срез ветки** (путь B, ORCH-088, доминирует на
+self-hosting `orchestrator`). Реализация **точно зеркалирует** прецедент `tasks.title`, как и
+предписал ADR-001: аддитивная колонка `tasks.description` через `_ensure_column`, записываемая
+**внутри того же атомарного INSERT** `create_task_atomic` (race-safe vs ORCH-053), читаемая в
+`_spawn` → `_materialize_deferred_branch` на момент claim (без сети в горячем пути, NFR-4). Тело
+рендерится чистым unit-тестируемым хелпером `_render_business_request` с fail-safe
+fallback-маркером.
+
+**Это независимый повторный review (v3).** Все 4 оси перепроверены лично против `origin/main`
+(`f50f61c`, = merge-base): скоуп `src/` — ровно 3 файла, предписанных ТЗ §2 (`webhooks/plane.py`,
+`agents/launcher.py`, `db.py`); тесты — `test_orch119_business_request.py` (новый, +263),
+`test_serial_gate_branch.py` (+spy-арг); `CHANGELOG.md` + work-item доки. **Полный прогон
+`pytest tests/ -q` — зелёный (2215 passed, изолированно от конкурентных сессий).**
+
+## Соответствие ТЗ / AC (ось 1) — PASS
+
+| AC / FR | Статус | Подтверждение |
+|---------|--------|---------------|
+| AC-1 / FR-1 — реальное описание вместо `TBD`, header/`Work Item ID` целы | ✅ | `_render_business_request` рендерит тело из `description`; TC-01 (genuine red→green). |
+| AC-2 / FR-2 — прямой путь A | ✅ | `start_pipeline` передаёт `description` в `_create_initial_docs` (`plane.py:736`); TC-04 ассертит отсутствие `## Description\n\nTBD\n`. |
+| AC-3 / FR-3 — отложенный путь B / durable-персист | ✅ | персист в атомарном INSERT `create_task_atomic` (`plane.py:665`, `db.py`); чтение `SELECT …, description` в `_spawn` → 5-й арг `_materialize_deferred_branch` (`_br_row[3]`); TC-03. |
+| AC-4 / FR-4 — fail-safe fallback | ✅ | `_BUSINESS_REQUEST_FALLBACK` + `try/except` → never-raise; TC-02 (`""`/`"   "`/`"\n\t"`/`None`). |
+| AC-5 — гейты/схема не тронуты | ✅ | коммит не касается `stages.py`/`qg/checks.py`; единственная схема — аддитивная `tasks.description`, базовый `CREATE TABLE tasks` цел; TC-07. |
+| AC-6 — идемпотентность / BC | ✅ | Gitea `422` → `return` (тело не перезаписывается, `plane.py:1006`); `_ensure_column` no-op; TC-05/TC-06. |
+| AC-7 — регресс red→green + полный прогон зелёный | ✅ | На `origin/main` `_render_business_request` **отсутствует** (grep=0) и `TBD` хардкоден (`plane.py:945`) → TC-01 настоящий red; green после. Полный прогон **2215 passed** (изолированно). |
+| AC-8 — сопровождение | ✅ | `CHANGELOG.md` содержит запись ORCH-119. |
+
+`description` определён в scope `start_pipeline` (`plane.py:538`) и **обогащается** из Plane API
+(`plane.py:560–568`) **до** обоих call-site (`:665`, `:736`) — NameError исключён; персистится тот
+же enriched-текст, что уходит analyst-job (`:751`) — консистентно.
+
+## Соответствие ADR (ось 2) — PASS
+
+- **D1** (аддитивная колонка в атомарном INSERT) — реализовано буквально:
+  `_ensure_column(conn,"tasks","description","TEXT")` рядом с `tasks.title`; запись встроена в
+  существующий INSERT `create_task_atomic`, не отдельным UPDATE → нет race-окна vs ORCH-053. ✅
+- **D2** (чистый рендер-хелпер + проброс на обоих путях) — `_render_business_request`
+  чистый/network-free; проброс A и B. ✅
+- **D3** (fail-safe fallback + идемпотентность) — маркер + never-raise + 422-no-op. ✅
+- **D4** (инварианты) — ORCH-088 момент/условие отложенного среза не меняются (дополняется только
+  источник данных), ORCH-053 семантика `(row, created)` цела, гейты байт-в-байт, без kill-switch
+  (обосновано — фикс дефекта). ✅
+- **Трассировка (TRACEABILITY):** правки блоков с маркерами **ORCH-088**
+  (`_materialize_deferred_branch`) и **ORCH-053** (`create_task_atomic`) сверены с их `06-adr` —
+  аддитивные, все новые параметры с дефолтами; зафиксированные инварианты не сломаны; комментарии
+  кода корректно ссылаются на оба ADR. ✅
+- Сквозной (global) ADR не требуется — локальное аддитивное решение по прецеденту. ✅
+
+## Качество кода (ось 3) — PASS
+
+- Чистый, network-free, unit-тестируемый хелпер; docstrings на всех новых/изменённых функциях. ✅
+- never-raise контракт соблюдён (`try/except` в рендере; создание задачи не падает). ✅
+- BC: все добавленные параметры аддитивны с дефолтами; единственный прочий потребитель сигнатуры
+  (`_docs_spy` в `test_serial_gate_branch.py`) синхронно обновлён под аддитивный `description=None`. ✅
+- **Багфикс-регресс (ORCH-019 / BR-4) — фиксатор присутствует:** TC-01 настоящий red до фикса
+  (`_render_business_request` отсутствовал + `_create_initial_docs` хардкодил `TBD` на `main`),
+  green после; усилен TC-04 (бьёт реальный баг-путь `_create_initial_docs`). ✅
+- Тесты содержательные: 7 TC покрывают регресс, fallback (4 параметра), оба пути, schema-BC,
+  идемпотентность 422, multiline/спецсимволы verbatim, анти-регресс гейтов. ✅
+- **Личная проверка:** `test_orch119_business_request.py` + `test_serial_gate_branch.py` — 13 passed;
+  `test_stage_engine.py` — 52 passed (изолированно); полный прогон — 2215 passed. ✅
+
+## Документация (ось 4) — PASS
+
+Изменён `src/` → проверка обязательна. Документация обновлена в том же PR:
+- **`CHANGELOG.md`** — подробная запись ORCH-119 (AC-8). ✅
+- **ADR-001** (`06-adr/ADR-001-source-backed-business-request-doc.md`) + **`08-data-requirements.md`**
+  (документирует схему `tasks.description`) — присутствуют, исчерпывающи. ✅
+- **API** — изменений нет (ТЗ §4) → таблица API в `docs/architecture/README.md` обновления не
+  требует. ✅
+- **Стадии/QG** — не тронуты → `docs/architecture/README.md` / `internals.md` обновления не
+  требуют. ✅
+- **Витрина `docs/overview/` (ORCH-011):** `tech-agents.md` по-прежнему верно указывает
+  `00-business-request.md` как вход аналитика; `tech-data-model.md` описывает `tasks`
+  концептуально (без перечня колонок) — добавление колонки его не устаревает; смена **тела**
+  артефакта (внутренняя деталь генерации) описанных стадий/гейтов/агентов/способностей не меняет.
+  Обновление не требуется. ✅
+- **`README.md` «Известные ограничения» (ORCH-079):** проверено — TBD-баг `00-business-request.md`
+  **не** числится среди 3 открытых ограничений (Telegram-48h / intra-repo deps / batch-автоном) —
+  закрывать/снимать нечего, обновление README не требуется. ✅
+- **Центрального schema-дока колонок `tasks` нет** — конвенция проекта: per-task скалярные колонки
+  документируются ADR задачи + data-requirements + CHANGELOG (так же оформлены `tasks.title` /
+  `tasks.track` / `tasks.cancelled_at`). ORCH-119 ей следует. ✅
+
+**Итог по документации:** при изменении `src/` документация обновлена в том же PR — P0 «`src/`
+изменён, документация не обновлена» **не наступает**.
+
+## Findings
+
+### P0 — Blocker
+- Нет.
+
+### P1 — Must fix
+- Нет.
+
+### P2 — Should fix
+- Нет.
+
+### P3 — Nice-to-have (не блокирует)
+- [ ] **`CHANGELOG.md` over-claim после rebase.** Хвост записи ORCH-119 описывает «Дополнительно в
+  том же PR починена тест-гермеичность `tests/test_orch123_staging_runner_exec.py`…». Этот файл
+  **отсутствует** в diff против `origin/main` — фикс (`fresh_db` пинит `repos_dir`) уже в `main`
+  (проверено: `git show origin/main:tests/test_orch123_staging_runner_exec.py` уже содержит пин).
+  Описывает изменение вне фактического скоупа PR (артефакт rebase). Безвредно (ядро ORCH-119
+  задокументировано точно), но для аккуратности — подрезать хвост. На корректность фикса не влияет.
+- [ ] `tests/test_orch119_business_request.py` мутирует `os.environ` (`ORCH_DB_PATH`/
+  `ORCH_REPOS_DIR`) на уровне модуля — добавляет к общей import-pollution-поверхности сьюта.
+  Соответствует существующей конвенции многих тест-файлов проекта (не новый грех), на корректность
+  не влияет.
+- [ ] `_render_business_request`: `try/except Exception` вокруг `(description or "").strip()` —
+  `.strip()` на строке не бросает, ветка недостижима. Намеренный never-break «belt-and-suspenders» в
+  стиле кодбейза; оставить как есть допустимо.
+
+## Документация
+
+**Статус: обновлена в том же PR — достаточно.** `CHANGELOG.md` (AC-8) + ADR-001 +
+`08-data-requirements.md` (схема `tasks.description`) — присутствуют и исчерпывающи. Витрина
+`docs/overview/`, обзорный `README.md` («Известные ограничения»),
+`PIPELINE_DOCS.md`/`HANDOFF_PROTOCOL.md` проверены явно — не устаревают (артефакт остаётся
+информационным, продюсер/владелец/гейт-статус не изменились; TBD-баг не числился среди открытых
+ограничений). Центрального schema-дока колонок `tasks` нет — аддитивная колонка документирована по
+конвенции (ADR + data-requirements + CHANGELOG, как `tasks.title`/`track`/`cancelled_at`).
+**Необновлённой обязательной документации не найдено.** (Единственный документ-нюанс — P3-over-claim
+в `CHANGELOG.md` про вне-скоупный `test_orch123`, не блокирует.)
+
+## Вердикт
+
+**APPROVED.** Нет P0/P1/P2. Все AC/FR/ADR удовлетворены; реализация — точное зеркало одобренного
+прецедента `tasks.title` с нулевым касанием конвейерной машинерии и сохранёнными инвариантами
+ORCH-088/ORCH-053; обязательный регресс-тест-фиксатор присутствует (genuine red→green, проверено
+против `origin/main`); полный прогон зелёный (2215 passed). Документация синхронна. Готово к стадии
+`testing`.

docs/work-items/ORCH-119/13-test-report.md

@@ -0,0 +1,40 @@
+---
+result: PASS
+work_item: ORCH-119
+stage: testing
+author_agent: test-runner
+status: success
+created_at: 2026-06-17
+model_used: n/a
+exit_code: 0
+smoke: ok
+---
+
+# Test Gate Log (deterministic runner, ORCH-116)
+
+pytest exit-code `0` -> `result: PASS` (smoke: ok).
+
+Вердикт зафиксирован детерминированным test-раннером (ORCH-116), не LLM. PASS/FAIL = exit-код `pytest` + read-only smoke (`/health`, `/status`, `/queue` + блок `serial_gate`).
+
+pytest stdout (tail):
+```
+............................................. [ 65%]
+........................................................................ [ 68%]
+........................................................................ [ 71%]
+........................................................................ [ 74%]
+........................................................................ [ 78%]
+........................................................................ [ 81%]
+........................................................................ [ 84%]
+........................................................................ [ 87%]
+........................................................................ [ 91%]
+........................................................................ [ 94%]
+........................................................................ [ 97%]
+.......................................................                  [100%]
+=============================== warnings summary ===============================
+src/config.py:8
+  /repos/_wt/orchestrator/feature_ORCH-119-bug-00-business-request-md-is-/src/config.py:8: PydanticDeprecatedSince20: Support for class-based `config` is deprecated, use ConfigDict instead. Deprecated in Pydantic V2.0 to be removed in V3.0. See Pydantic V2 Migration Guide at https://errors.pydantic.dev/2.13/migration/
+    class Settings(BaseSettings):
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+2215 passed, 1 warning in 105.47s (0:01:45)
+```

docs/work-items/ORCH-119/14-deploy-log.md

@@ -0,0 +1,12 @@
+---
+deploy_status: SUCCESS
+work_item: ORCH-119
+hook_exit_code: 0
+deployed_by: deploy-finalizer
+---
+
+# Deploy log — ORCH-036 executable self-deploy
+
+Прод-деплой завершён хост-хуком с exit-code `0` -> `deploy_status: SUCCESS`.
+
+Вердикт зафиксирован детерминированным finalizer'ом (Фаза C), не LLM.

docs/work-items/ORCH-119/15-staging-log.md

@@ -0,0 +1,46 @@
+---
+staging_status: SUCCESS
+work_item: ORCH-119
+stage: deploy-staging
+author_agent: staging-runner
+status: success
+created_at: 2026-06-17
+model_used: n/a
+exit_code: 0
+base_url: http://localhost:8501
+---
+
+# Staging Gate Log (deterministic runner, ORCH-115)
+
+Staging suite exit-code `0` -> `staging_status: SUCCESS`.
+
+Вердикт зафиксирован детерминированным staging-раннером (ORCH-115), не LLM. infra-tolerance (ORCH-061) уже учтена внутри `staging_check.py` — раннер её не пересуживает.
+
+INFRA-WAIVED lines (ORCH-061, copied for observability):
+- INFRA-WAIVED: C9a Branch appears in orchestrator-sandbox, C9b Analyst job enqueued in staging queue (known sandbox-infra; real checks green)
+
+Staging suite stdout (tail):
+```
+ (waiting for analyst job in queue)
+  ·        waiting... (waiting for analyst job in queue)
+  ·        waiting... (waiting for analyst job in queue)
+  ·        waiting... (waiting for analyst job in queue)
+  ·        waiting... (waiting for analyst job in queue)
+  ·        waiting... (waiting for analyst job in queue)
+  ✗ FAIL  C9b Analyst job enqueued in staging queue
+
+[CLEANUP]
+  ·      CLEANUP: no branch to delete
+  ✓ PASS  CLEANUP: deleted Plane issue 0c163a41-a2a8-4884-b1f7-77017bce8d50 (HTTP 204)
+  ·      CLEANUP DB: no task row found for plane_id=0c163a41-a2a8-4884-b1f7-77017bce8d50
+  ·      CLEANUP DB dedup: no such table: events_dedup
+
+============================================================
+  RESULT: 8/10 checks PASS
+  REAL failed         : none
+  SANDBOX_INFRA failed: ['C9a Branch appears in orchestrator-sandbox', 'C9b Analyst job enqueued in staging queue']
+============================================================
+  ·      tolerance: staging_infra_tolerance_enabled=True
+INFRA-WAIVED: C9a Branch appears in orchestrator-sandbox, C9b Analyst job enqueued in staging queue (known sandbox-infra; real checks green)
+VERDICT: SUCCESS (exit 0) — SUCCESS (infra-waived): ['C9a Branch appears in orchestrator-sandbox', 'C9b Analyst job enqueued in staging queue'] are known sandbox-infra checks; all real checks green
+```

docs/work-items/ORCH-119/17-security-report.md

@@ -0,0 +1,29 @@
+---
+security_status: PASS
+secrets_found: 0
+deps_blocking: 0
+deps_warning: 8
+deps_audit_degraded: false
+---
+# Security Report — ORCH-119
+
+Детерминированный security-гейт (ORCH-022): secret-scanning (gitleaks, offline) + dependency audit (pip-audit). Машинный вердикт читается ТОЛЬКО из frontmatter выше.
+
+## Verdict
+clean: 0 secrets, 0 blocking CVE(s)
+
+## Secrets
+- None
+
+## Dependencies (blocking)
+- None
+
+## Dependencies (warning)
+- `pytest==8.3.3` — GHSA-6w46-j5rx-g56g severity=UNKNOWN fix=9.0.3
+- `starlette==0.38.6` — PYSEC-2026-161 severity=UNKNOWN fix=1.0.1
+- `starlette==0.38.6` — GHSA-f96h-pmfr-66vw severity=UNKNOWN fix=0.40.0
+- `starlette==0.38.6` — GHSA-2c2j-9gv5-cj73 severity=UNKNOWN fix=0.47.2
+- `starlette==0.38.6` — GHSA-wqp7-x3pw-xc5r severity=UNKNOWN fix=1.1.0
+- `starlette==0.38.6` — GHSA-x746-7m8f-x49c severity=UNKNOWN fix=1.1.0
+- `starlette==0.38.6` — GHSA-82w8-qh3p-5jfq severity=UNKNOWN fix=1.3.1
+- `starlette==0.38.6` — GHSA-jp82-jpqv-5vv3 severity=UNKNOWN fix=1.3.0

docs/work-items/ORCH-120/16-post-deploy-log.md

@@ -1,14 +0,0 @@
----
-post_deploy_status: HEALTHY
-action_taken: NONE
-work_item: ORCH-120
-window_s: 900
-checks_total: 30
-checks_failed: 0
----
-
-# Post-deploy log — ORCH-021 post-deploy monitor
-
-Наблюдение прода завершено: `post_deploy_status: HEALTHY`, `action_taken: NONE`.
-
-Окно наблюдения: 900s; опросов всего: 30, из них с провалом: 0.

scripts/onboard_project.py

@@ -82,6 +82,10 @@ STATE_GROUPS: dict[str, str] = {
     "Backlog": "backlog",
     "Todo": "unstarted",
     "To Analyse": "unstarted",
+    # ORCH-020: «Оценка» — transient backlog-side estimation trigger. Group MUST be
+    # non-terminal (unstarted/backlog), NEVER completed/cancelled — otherwise the
+    # ORCH-068 terminal-detection would falsely terminate the issue mid-estimate.
+    "Оценка": "unstarted",
     "In Progress": "started",
     "Analysis": "started",
     "Architecture": "started",
@@ -934,7 +938,7 @@ def run_verify(
         report.add("verify.registry", "запись реестра ORCH_PROJECTS_JSON", OK,
                    f"prefix={entry.work_item_prefix}, repo={entry.repo}")
 
-    # 2. Статусы: все 22 канонических имени (включая fail-closed Confirm Deploy/STOP).
+    # 2. Статусы: все 23 канонических имени (включая fail-closed Confirm Deploy/STOP/Оценка).
     if observed.project is None or observed.states is None:
         report.add("verify.plane.states", "статусы Plane-проекта", GAP,
                    "проект/статусы не читаются через API")

src/agents/launcher.py

@@ -512,7 +512,8 @@ class AgentLauncher:
         return None
 
     def _materialize_deferred_branch(
-        self, repo: str, branch: str, work_item_id: str | None, title: str | None
+        self, repo: str, branch: str, work_item_id: str | None, title: str | None,
+        description: str | None = None,
     ) -> None:
         """ORCH-088 (ADR-001 D1): create the deferred Gitea branch + initial docs.
 
@@ -524,6 +525,12 @@ class AgentLauncher:
         Both are idempotent (409/422 -> no-op) so a re-claim after a restart is safe.
         A transient Gitea error PROPAGATES so the caller (_spawn) fails the launch and
         the queue worker requeues the job for a later tick (never a half-cut state).
+
+        ORCH-119 (FR-3 / AC-3): ``description`` (read from the tasks row by ``_spawn``,
+        durable since task creation) is passed through to ``_create_initial_docs`` so
+        the artifact materialised at claim carries the real request text, not ``TBD``.
+        The branch-cut MOMENT/CONDITION are unchanged — only the data source is enriched
+        (ORCH-088 anti-stale-base invariant preserved, NFR-3).
         """
         import asyncio
         from ..webhooks.plane import _create_gitea_branch, _create_initial_docs
@@ -535,7 +542,9 @@ class AgentLauncher:
         )
         asyncio.run(_create_gitea_branch(repo, branch))
         if work_item_id:
-            asyncio.run(_create_initial_docs(repo, branch, work_item_id, name))
+            asyncio.run(
+                _create_initial_docs(repo, branch, work_item_id, name, description)
+            )
 
     def _spawn(self, agent: str, repo: str, task_content: str = None,
                task_id: int = None, job_id: int = None) -> int:
@@ -556,9 +565,14 @@ class AgentLauncher:
             raise FileNotFoundError(f"Repo not found: {local_repo_path}")
 
         # Determine branch (needed before we touch the worktree / task file).
+        # ORCH-119: also read the durable `description` so the deferred branch
+        # materialisation (path B) renders the real request text into
+        # 00-business-request.md instead of `TBD`. No network call (read from the
+        # tasks row) -> the hot claim path stays network-free (NFR-4).
         _br_row = (
             get_db().execute(
-                "SELECT branch, work_item_id, title FROM tasks WHERE id=?", (task_id,)
+                "SELECT branch, work_item_id, title, description FROM tasks WHERE id=?",
+                (task_id,),
             ).fetchone()
             if task_id else None
         )
@@ -580,7 +594,7 @@ class AgentLauncher:
                 _applies = False
             if _applies:
                 self._materialize_deferred_branch(
-                    repo, agent_branch, _br_row[1], _br_row[2]
+                    repo, agent_branch, _br_row[1], _br_row[2], _br_row[3]
                 )
 
         # ORCH-41: resolve the Plane project uuid for this repo so per-project

src/config.py

@@ -1196,6 +1196,51 @@ class Settings(BaseSettings):
     bug_fast_track_label: str = "Bug"
     bug_fast_track_repos: str = ""
 
+    # ORCH-020: task-estimation side-mechanism, triggered by the operator Plane status
+    # «Оценка» (third member of the action-status family STOP/Confirm Deploy). A leaf
+    # src/estimator.py (never-raise) forecasts cost/time/tokens/story-points from the
+    # history of completed tasks (deterministic heuristic, NO LLM — ADR-001 D1),
+    # writes the forecast to Plane (estimate_point + comment), the Telegram card and
+    # the additive task_estimates ledger (UPSERT by work_item_id), then returns the
+    # issue to Backlog. On task completion (-> done) the fact is written to Plane
+    # `point`. The estimator is an OBSERVER/PRODUCER, never a Quality Gate / stage:
+    # STAGE_TRANSITIONS / QG_CHECKS / check_* / verdict-keys / existing schemas are NOT
+    # touched. Pattern = bug_fast_track_* / coverage_gate_* (kill-switch + CSV scope,
+    # applies() local & FIRST). See docs/work-items/ORCH-020/06-adr/ADR-001-task-
+    # estimation-status-trigger.md and docs/architecture/adr/adr-0054-task-estimation-
+    # status-trigger.md.
+    #   estimator_enabled           -> SINGLE kill-switch (env ORCH_ESTIMATOR_ENABLED).
+    #                                  False -> the «Оценка» status is not handled, no
+    #                                  Plane/card/table write — pipeline 1:1 as before
+    #                                  ORCH-020, zero regression (AC-9).
+    #   estimator_repos             -> CSV scope (env ORCH_ESTIMATOR_REPOS). Empty ->
+    #                                  self-hosting only (orchestrator) via
+    #                                  is_self_hosting_repo; non-empty -> membership.
+    #                                  Mirrors coverage_gate_repos -> enduro untouched.
+    #   estimator_min_samples       -> history size below which the bootstrap default
+    #                                  blends in (D2). Default 3.
+    #   estimator_bootstrap_tokens  -> cold-start token forecast when history is empty.
+    #   estimator_bootstrap_cost_usd-> cold-start cost ($) forecast (drives the
+    #                                  bootstrap story-point bucket: 3.0 -> «3» medium).
+    #   estimator_bootstrap_seconds -> cold-start wall-time forecast.
+    #   estimator_sp_cost_thresholds-> CSV of 4 ascending cost cut-offs (t1,t2,t3,t5),
+    #                                  `<=` ascending: <=t1->1, <=t2->2, <=t3->3,
+    #                                  <=t5->5, else 8 (D3). Re-calibratable on ORCH-13.
+    #   estimator_wall_cap_s        -> cap on anomalous wall-time in history (a task
+    #                                  parked in backlog for days would skew the mean);
+    #                                  mirror of tracker_brd_review_cap_s. Default 24h.
+    #   estimator_max_inflight      -> optional smoothing semaphore for bulk multi-select
+    #                                  (v1 generous/off; not enforced).
+    estimator_enabled: bool = True
+    estimator_repos: str = ""
+    estimator_min_samples: int = 3
+    estimator_bootstrap_tokens: int = 2_000_000
+    estimator_bootstrap_cost_usd: float = 3.0
+    estimator_bootstrap_seconds: int = 1800
+    estimator_sp_cost_thresholds: str = "0.50,2.00,5.00,12.00"
+    estimator_wall_cap_s: int = 86400
+    estimator_max_inflight: int = 64
+
     # Telegram notifications
     telegram_bot_token: str = ""
     telegram_chat_id: str = ""

src/db.py

@@ -123,6 +123,16 @@ def init_db():
     # ("🛠️ ET-012 · <title>"). Populated from the Plane work-item name at task
     # creation; falls back to the work_item_id when absent. Idempotent ALTER.
     _ensure_column(conn, "tasks", "title", "TEXT")
+    # ORCH-119 (08-data-requirements.md): durable source-backed Plane-issue
+    # `description` (plain-text, preferably description_stripped). Mirrors tasks.title
+    # 1:1 — additive, idempotent (_ensure_column is a no-op once present) -> safe on
+    # the live shared prod DB (enduro untouched). Written inside the atomic INSERT in
+    # create_task_atomic so it is race-safe vs the ORCH-053 anti-dup claim (no window
+    # where the task exists but the description is missing). The deferred branch cut
+    # (path B, ORCH-088, dominates on self-hosting) reads it from the tasks row at
+    # claim time and renders it into 00-business-request.md instead of the historic
+    # hardcoded `TBD`. NULL for pre-existing rows -> renders the safe fallback marker.
+    _ensure_column(conn, "tasks", "description", "TEXT")
     # Telegram live tracker: "BRD review" is the only HUMAN gate time — the delta
     # between "BRD ready / approve requested" and the analysis->architecture
     # advance (human flipped Plane to Approved). Persisted on the task so the
@@ -296,6 +306,39 @@ def init_db():
             acquired_at   TEXT NOT NULL DEFAULT (datetime('now'))
         );
     """)
+    # ORCH-020 (adr-0054 / 08-data-requirements.md): additive task-estimation ledger
+    # (forecast<->fact, keyed by work_item_id because an issue may have NO task row at
+    # estimate time — it sits in the backlog). ONE additive object (CREATE TABLE/INDEX
+    # IF NOT EXISTS, pattern coverage_baseline/lessons/transition_lease) -> idempotent,
+    # restart-safe on the shared prod DB; existing tables (tasks/agent_runs/jobs/...)
+    # untouched byte-for-byte (NFR-8). UNIQUE(work_item_id) is the carrying invariant
+    # of idempotent re-estimation (BR-T4/AC-T4): a repeat «Оценка» UPSERTs the one row
+    # and bumps estimate_count; no duplicate rows. The forecast<->fact delta is computed
+    # on read (not a stored column) to avoid drift. The estimator leaf wraps every call
+    # below in its never-raise contract. enduro-trails is not affected — the table is
+    # shared but only the self-hosting scope writes to it.
+    conn.executescript("""
+        CREATE TABLE IF NOT EXISTS task_estimates (
+            id                    INTEGER PRIMARY KEY AUTOINCREMENT,
+            work_item_id          TEXT NOT NULL UNIQUE,
+            task_id               INTEGER,
+            repo                  TEXT,
+            forecast_tokens       INTEGER,
+            forecast_seconds      INTEGER,
+            forecast_cost_usd     REAL,
+            forecast_story_points INTEGER,
+            actual_tokens         INTEGER,
+            actual_seconds        INTEGER,
+            actual_cost_usd       REAL,
+            actual_story_points   INTEGER,
+            source                TEXT,
+            estimate_count        INTEGER NOT NULL DEFAULT 1,
+            created_at            TEXT NOT NULL DEFAULT (datetime('now')),
+            updated_at            TEXT
+        );
+        CREATE INDEX IF NOT EXISTS idx_task_estimates_repo    ON task_estimates (repo);
+        CREATE INDEX IF NOT EXISTS idx_task_estimates_task_id ON task_estimates (task_id);
+    """)
     conn.commit()
     conn.close()
 
@@ -556,6 +599,204 @@ def all_coverage_baselines() -> dict:
     }
 
 
+# ---------------------------------------------------------------------------
+# ORCH-020 (adr-0054, ADR-001 D7): task-estimation ledger helpers. Each opens its
+# own connection and closes it in `finally` (pattern coverage_baseline/lessons). The
+# leaf src/estimator.py wraps these in its never-raise contract — they may raise on a
+# real DB fault (the leaf swallows it).
+# ---------------------------------------------------------------------------
+def record_estimate(
+    work_item_id: str,
+    repo: str = None,
+    task_id: int = None,
+    forecast_tokens: int = None,
+    forecast_seconds: int = None,
+    forecast_cost_usd: float = None,
+    forecast_story_points: int = None,
+    source: str = "status",
+) -> int:
+    """UPSERT a forecast by ``work_item_id`` (BR-T4/AC-T4 idempotent re-estimation).
+
+    On first insert ``estimate_count`` is 1; a repeat (same work_item_id) updates the
+    forecast in place, bumps ``estimate_count`` and stamps ``updated_at`` — no
+    duplicate rows. ``task_id`` is COALESCEd so a later start-of-pipeline link is not
+    wiped by a re-estimate that still sees a NULL task. Returns the row id.
+    """
+    if not work_item_id:
+        raise ValueError("record_estimate requires work_item_id")
+    conn = get_db()
+    try:
+        conn.execute(
+            "INSERT INTO task_estimates "
+            "  (work_item_id, repo, task_id, forecast_tokens, forecast_seconds, "
+            "   forecast_cost_usd, forecast_story_points, source, estimate_count, updated_at) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?, ?, 1, datetime('now')) "
+            "ON CONFLICT(work_item_id) DO UPDATE SET "
+            "  repo = COALESCE(excluded.repo, task_estimates.repo), "
+            "  task_id = COALESCE(excluded.task_id, task_estimates.task_id), "
+            "  forecast_tokens = excluded.forecast_tokens, "
+            "  forecast_seconds = excluded.forecast_seconds, "
+            "  forecast_cost_usd = excluded.forecast_cost_usd, "
+            "  forecast_story_points = excluded.forecast_story_points, "
+            "  source = excluded.source, "
+            "  estimate_count = task_estimates.estimate_count + 1, "
+            "  updated_at = datetime('now')",
+            (
+                work_item_id, repo, task_id, forecast_tokens, forecast_seconds,
+                forecast_cost_usd, forecast_story_points, source,
+            ),
+        )
+        conn.commit()
+        row = conn.execute(
+            "SELECT id FROM task_estimates WHERE work_item_id = ?", (work_item_id,)
+        ).fetchone()
+        return int(row["id"]) if row else 0
+    finally:
+        conn.close()
+
+
+def set_actual(
+    work_item_id: str,
+    actual_tokens: int = None,
+    actual_seconds: int = None,
+    actual_cost_usd: float = None,
+    actual_story_points: int = None,
+    task_id: int = None,
+) -> bool:
+    """Write the FACT half of the ledger (on task completion). Never touches the
+    forecast columns (AC-4: the fact must not overwrite the prediction). Returns True
+    iff a row was updated/inserted.
+
+    If no forecast row exists yet (an issue completed without ever being estimated) a
+    fact-only row is inserted so the ledger still records the actuals.
+    """
+    if not work_item_id:
+        return False
+    conn = get_db()
+    try:
+        cur = conn.execute(
+            "UPDATE task_estimates SET "
+            "  actual_tokens = ?, actual_seconds = ?, actual_cost_usd = ?, "
+            "  actual_story_points = ?, "
+            "  task_id = COALESCE(?, task_id), updated_at = datetime('now') "
+            "WHERE work_item_id = ?",
+            (
+                actual_tokens, actual_seconds, actual_cost_usd, actual_story_points,
+                task_id, work_item_id,
+            ),
+        )
+        changed = cur.rowcount or 0
+        if changed == 0:
+            conn.execute(
+                "INSERT INTO task_estimates "
+                "  (work_item_id, task_id, actual_tokens, actual_seconds, "
+                "   actual_cost_usd, actual_story_points, source, updated_at) "
+                "VALUES (?, ?, ?, ?, ?, ?, 'fact-only', datetime('now'))",
+                (
+                    work_item_id, task_id, actual_tokens, actual_seconds,
+                    actual_cost_usd, actual_story_points,
+                ),
+            )
+            changed = 1
+        conn.commit()
+        return bool(changed)
+    finally:
+        conn.close()
+
+
+def get_estimate(work_item_id: str) -> dict | None:
+    """Return the current forecast/fact row for ``work_item_id`` (None when absent)."""
+    if not work_item_id:
+        return None
+    conn = get_db()
+    try:
+        row = conn.execute(
+            "SELECT * FROM task_estimates WHERE work_item_id = ?", (work_item_id,)
+        ).fetchone()
+    finally:
+        conn.close()
+    return dict(row) if row else None
+
+
+def estimates_snapshot(limit: int = 10) -> dict:
+    """Light summary (totals + last N rows) for the GET /queue estimator block."""
+    try:
+        lim = max(1, int(limit))
+    except (TypeError, ValueError):
+        lim = 10
+    conn = get_db()
+    try:
+        total = conn.execute("SELECT COUNT(*) FROM task_estimates").fetchone()[0]
+        with_actual = conn.execute(
+            "SELECT COUNT(*) FROM task_estimates WHERE actual_story_points IS NOT NULL"
+        ).fetchone()[0]
+        rows = conn.execute(
+            "SELECT work_item_id, repo, forecast_story_points, actual_story_points, "
+            "forecast_cost_usd, actual_cost_usd, estimate_count, updated_at "
+            "FROM task_estimates ORDER BY id DESC LIMIT ?",
+            (lim,),
+        ).fetchall()
+    finally:
+        conn.close()
+    return {
+        "total": total,
+        "with_actual": with_actual,
+        "recent": [dict(r) for r in rows],
+    }
+
+
+def completed_task_stats(repo: str, track: str) -> dict:
+    """ORCH-020 (ADR-001 D2): read-only history aggregate over COMPLETED tasks of
+    ``repo`` + ``track`` (full/bug). The basis of the forecast.
+
+    Tokens (input + cache_read + cache_creation + output) and cost are summed per
+    completed task from ``agent_runs``; wall-time is ``updated_at - created_at`` of the
+    ``tasks`` row, capped at ``wall_cap_s`` to drop anomalous backlog stalls. Returns
+    ``{n, mean_tokens, mean_cost_usd, mean_seconds}`` (means over the completed tasks;
+    ``n=0`` -> all means 0.0, the caller then bootstraps). Reads ONLY existing tables;
+    introduces no columns. Raises only on a real DB fault (the leaf wraps it).
+    """
+    from .config import settings
+    try:
+        wall_cap = int(getattr(settings, "estimator_wall_cap_s", 86400) or 0)
+    except (TypeError, ValueError):
+        wall_cap = 86400
+    conn = get_db()
+    try:
+        rows = conn.execute(
+            "SELECT t.id AS tid, "
+            "  CAST(strftime('%s', t.updated_at) - strftime('%s', t.created_at) AS INTEGER) AS wall_s, "
+            "  COALESCE(SUM(ar.input_tokens),0) + COALESCE(SUM(ar.cache_read_tokens),0) "
+            "    + COALESCE(SUM(ar.cache_creation_tokens),0) + COALESCE(SUM(ar.output_tokens),0) AS tokens, "
+            "  COALESCE(SUM(ar.cost_usd),0.0) AS cost "
+            "FROM tasks t LEFT JOIN agent_runs ar ON ar.task_id = t.id "
+            "WHERE t.repo = ? AND t.stage = 'done' AND COALESCE(t.track,'full') = ? "
+            "GROUP BY t.id",
+            (repo, track),
+        ).fetchall()
+    finally:
+        conn.close()
+    n = len(rows)
+    if n == 0:
+        return {"n": 0, "mean_tokens": 0.0, "mean_cost_usd": 0.0, "mean_seconds": 0.0}
+    sum_tokens = 0.0
+    sum_cost = 0.0
+    wall_values = []
+    for r in rows:
+        sum_tokens += float(r["tokens"] or 0)
+        sum_cost += float(r["cost"] or 0.0)
+        w = r["wall_s"]
+        if w is not None and w > 0:
+            wall_values.append(min(int(w), wall_cap) if wall_cap > 0 else int(w))
+    mean_seconds = (sum(wall_values) / len(wall_values)) if wall_values else 0.0
+    return {
+        "n": n,
+        "mean_tokens": sum_tokens / n,
+        "mean_cost_usd": sum_cost / n,
+        "mean_seconds": mean_seconds,
+    }
+
+
 def _ensure_column(conn, table: str, column: str, decl: str):
     """Add a column to `table` if it does not already exist (idempotent migration)."""
     cols = [r[1] for r in conn.execute(f"PRAGMA table_info({table})").fetchall()]
@@ -662,6 +903,7 @@ def create_task_atomic(
     branch: str,
     stage: str,
     title: str,
+    description: str | None = None,
 ) -> tuple[dict, bool]:
     """ORCH-053 (AC-4): atomically claim creation of a task for a plane_id.
 
@@ -676,6 +918,14 @@ def create_task_atomic(
       * ``created=False`` -> a task for this plane_id already existed (the other
         racer won); ``row`` is the existing task and the caller must NOT duplicate
         the follow-up work.
+
+    ORCH-119 (ADR-001 D1): ``description`` (the source-backed Plane-issue text) is
+    persisted durable INSIDE this same atomic INSERT — never a separate UPDATE — so
+    there is no race window (ORCH-053) where the task exists but the description is
+    missing. The parameter is additive with a default so the other callers (e.g. the
+    F-2 reconciler) stay backward-compatible (NULL description -> render falls back to
+    a safe marker). The deferred branch cut (path B, ORCH-088) reads it from the row
+    at claim time.
     """
     with _CREATE_TASK_LOCK:
         conn = get_db()
@@ -688,9 +938,11 @@ def create_task_atomic(
                 return dict(existing), False
             cur = conn.execute(
                 "INSERT INTO tasks "
-                "(plane_id, work_item_id, repo, branch, stage, plane_issue_id, title) "
-                "VALUES (?, ?, ?, ?, ?, ?, ?)",
-                (plane_id, work_item_id, repo, branch, stage, plane_id, title),
+                "(plane_id, work_item_id, repo, branch, stage, plane_issue_id, title, "
+                "description) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+                (plane_id, work_item_id, repo, branch, stage, plane_id, title,
+                 description),
             )
             conn.commit()
             row = conn.execute(

src/estimator.py

@@ -0,0 +1,444 @@
+"""ORCH-020: task-estimation side-mechanism, triggered by the operator Plane status
+«Оценка» (the third member of the action-status family STOP/Confirm Deploy).
+
+Leaf module — pure, unit-testable logic over the config flags + a deterministic
+heuristic over the history of completed tasks (NO LLM call — ADR-001 D1). Mirrors the
+leaf pattern of ``src/bug_fast_track.py`` / ``src/coverage_gate.py`` / ``src/lessons.py``:
+imports only ``config`` at module load (and lazily ``db`` / ``usage`` / ``plane_sync`` /
+``notifications`` / ``qg.checks``), never ``stage_engine`` / ``launcher``.
+
+What it does (ADR-001):
+  * ``applies(repo)`` — kill-switch + CSV scope (empty -> self-hosting only), evaluated
+    LOCALLY and FIRST so a disabled flag costs zero network and yields zero regression.
+  * ``should_estimate(task)`` — anti-disruption (BR-T6): an issue with an ACTIVE
+    (queued/running) job is NOT yanked into a re-estimate; a backlog issue (no task) or
+    a terminal/idle task is fair game.
+  * ``estimate(work_item_id, issue, repo)`` — the producer: forecast {tokens, seconds,
+    cost_usd, story_points} from the history of similar (repo+track) completed tasks
+    (bootstrap default on a cold start), UPSERT it into ``task_estimates`` (idempotent
+    re-estimation by work_item_id), write it to Plane (``estimate_point`` + comment) and
+    refresh the Telegram card. This is the extension boundary D1: a future hybrid LLM
+    refiner plugs in behind ``_forecast`` without changing callers.
+  * ``story_points_for(forecast)`` — pure bucketiser: cost -> {1,2,3,5,8} (D3).
+  * ``record_actual_on_done(task_id, repo, work_item_id)`` — on completion, derive the
+    FACT from ``usage.py`` and write it to Plane ``point`` + the ledger (D9).
+  * ``snapshot()`` — read-only GET /queue block (D11).
+
+INVARIANT (NFR-1/NFR-3): the estimator is an OBSERVER/PRODUCER, never a Quality Gate or
+a stage transition. It never touches STAGE_TRANSITIONS / QG_CHECKS / check_* /
+machine-verdict keys / the hot path. never-raise contract: every public function
+degrades to a safe default on ANY error — a broken estimate can never crash the webhook
+flow or the pipeline.
+"""
+from __future__ import annotations
+
+import logging
+
+from .config import settings
+
+logger = logging.getLogger("orchestrator.estimator")
+
+# Fixed story-point scale (BR-3 / FR-T4). Values outside this set are never emitted.
+_STORY_POINTS = (1, 2, 3, 5, 8)
+_DEFAULT_SP_THRESHOLDS = (0.50, 2.00, 5.00, 12.00)
+
+# In-process observability counters (reset on restart; mirror merge_gate / staging_runner).
+_COUNTERS = {
+    "forecasts": 0,       # estimate() runs that produced a forecast
+    "plane_writes": 0,    # successful estimate_point writes
+    "backlog_returns": 0, # set_issue_backlog calls after an estimate
+    "actuals": 0,         # record_actual_on_done runs that wrote a fact
+}
+
+
+# ---------------------------------------------------------------------------
+# Scope / kill-switch (mirrors bug_fast_track_applies / coverage_gate_applies)
+# ---------------------------------------------------------------------------
+def applies(repo: str) -> bool:
+    """Whether estimation is REAL for ``repo`` (ADR-001 D11 / AC-9).
+
+      * ``estimator_enabled=False`` -> always False (kill-switch; the «Оценка» status
+        is not handled, nothing is written — zero regression).
+      * ``estimator_repos`` (CSV) non-empty -> real only for the listed repos.
+      * empty CSV -> self-hosting only (``orchestrator``) — the safe default (enduro
+        opts in via an explicit CSV entry).
+    Checked FIRST (local, network-free); never raises -> False on error.
+    """
+    try:
+        if not getattr(settings, "estimator_enabled", False):
+            return False
+        raw = (getattr(settings, "estimator_repos", "") or "").strip()
+        if raw:
+            allowed = {r.strip().lower() for r in raw.split(",") if r.strip()}
+            return (repo or "").strip().lower() in allowed
+        from .qg.checks import is_self_hosting_repo
+        return is_self_hosting_repo(repo)
+    except Exception as e:  # noqa: BLE001 - never-raise -> inert
+        logger.warning("estimator.applies error for %s: %s", repo, e)
+        return False
+
+
+def should_estimate(task: dict | None) -> bool:
+    """Anti-disruption predicate (BR-T6 / AC-T6).
+
+    True when estimation may proceed: a backlog issue (``task is None``) or a
+    terminal/idle pipeline task. False when the task has an ACTIVE (queued/running) job
+    — re-estimating it would mean yanking in-flight work back to Backlog. On ANY error
+    -> False (fail-safe: never disrupt on doubt).
+    """
+    try:
+        if not task:
+            return True
+        tid = task.get("id")
+        if tid is None:
+            return True
+        from .db import has_active_job_for_task
+        return not has_active_job_for_task(int(tid))
+    except Exception as e:  # noqa: BLE001 - fail-safe: do not disrupt
+        logger.warning("estimator.should_estimate error: %s", e)
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Story-point bucketiser — pure function, configurable cost thresholds (D3)
+# ---------------------------------------------------------------------------
+def _sp_thresholds() -> tuple[float, float, float, float]:
+    """Parse ``estimator_sp_cost_thresholds`` (CSV of 4 ascending cut-offs).
+
+    Malformed / wrong-arity / non-ascending -> the safe defaults. Pure, never raises.
+    """
+    raw = getattr(settings, "estimator_sp_cost_thresholds", "") or ""
+    try:
+        parts = [float(p.strip()) for p in str(raw).split(",") if p.strip()]
+        if len(parts) == 4 and all(parts[i] <= parts[i + 1] for i in range(3)):
+            return (parts[0], parts[1], parts[2], parts[3])
+    except (TypeError, ValueError):
+        pass
+    return _DEFAULT_SP_THRESHOLDS
+
+
+def story_points_for(forecast) -> int:
+    """Map a cost (or a forecast dict carrying a cost) -> a story point in {1,2,3,5,8}.
+
+    Primary signal is **cost in USD** (the «how much will it cost» axis the customer
+    asked for; re-calibratable by config on a tariff change, ORCH-13). Semantics
+    (``<=`` ascending, D3): ``cost <= t1 -> 1`` · ``<= t2 -> 2`` · ``<= t3 -> 3`` ·
+    ``<= t5 -> 5`` · else ``8``. Pure; never raises (any bad input -> the lowest bucket
+    is avoided in favour of a safe mid value only on hard error).
+    """
+    try:
+        if isinstance(forecast, dict):
+            cost = forecast.get("forecast_cost_usd", forecast.get("cost_usd", 0.0))
+        else:
+            cost = forecast
+        cost = float(cost or 0.0)
+    except (TypeError, ValueError):
+        return 3  # safe middle on a malformed input (never an off-scale value)
+    t1, t2, t3, t5 = _sp_thresholds()
+    if cost <= t1:
+        return 1
+    if cost <= t2:
+        return 2
+    if cost <= t3:
+        return 3
+    if cost <= t5:
+        return 5
+    return 8
+
+
+# ---------------------------------------------------------------------------
+# Forecast core — deterministic heuristic over completed-task history (D2)
+# ---------------------------------------------------------------------------
+def _bootstrap_forecast() -> dict:
+    """Cold-start forecast from the config bootstrap defaults (no history)."""
+    tokens = int(getattr(settings, "estimator_bootstrap_tokens", 2_000_000) or 0)
+    cost = float(getattr(settings, "estimator_bootstrap_cost_usd", 3.0) or 0.0)
+    seconds = int(getattr(settings, "estimator_bootstrap_seconds", 1800) or 0)
+    return {
+        "forecast_tokens": tokens,
+        "forecast_seconds": seconds,
+        "forecast_cost_usd": round(cost, 4),
+        "story_points": story_points_for(cost),
+    }
+
+
+def _forecast(repo: str, track: str) -> dict:
+    """Compute the forecast for a (repo, track) pair from history (ADR-001 D1/D2).
+
+    Forecast = means over similar COMPLETED tasks (same repo + track). Below
+    ``estimator_min_samples`` the bootstrap default blends in linearly (weight = n /
+    min_samples toward the observed mean, the remainder toward bootstrap), so a small
+    history still nudges the cold start. ``n == 0`` -> pure bootstrap. Never an
+    exception (AC-1): any error -> bootstrap default.
+    """
+    try:
+        from . import db
+        stats = db.completed_task_stats(repo, track) or {}
+        n = int(stats.get("n", 0) or 0)
+        boot = _bootstrap_forecast()
+        if n <= 0:
+            return boot
+        obs_tokens = float(stats.get("mean_tokens", 0.0) or 0.0)
+        obs_cost = float(stats.get("mean_cost_usd", 0.0) or 0.0)
+        obs_seconds = float(stats.get("mean_seconds", 0.0) or 0.0)
+        min_samples = max(1, int(getattr(settings, "estimator_min_samples", 3) or 3))
+        if n >= min_samples:
+            tokens, cost, seconds = obs_tokens, obs_cost, obs_seconds
+        else:
+            # Linear blend (D2): more samples -> trust the observation more.
+            w = n / min_samples
+            tokens = w * obs_tokens + (1 - w) * boot["forecast_tokens"]
+            cost = w * obs_cost + (1 - w) * boot["forecast_cost_usd"]
+            seconds = w * obs_seconds + (1 - w) * boot["forecast_seconds"]
+        return {
+            "forecast_tokens": int(round(tokens)),
+            "forecast_seconds": int(round(seconds)),
+            "forecast_cost_usd": round(float(cost), 4),
+            "story_points": story_points_for(cost),
+        }
+    except Exception as e:  # noqa: BLE001 - never-raise -> bootstrap default
+        logger.warning("estimator._forecast error for %s/%s: %s", repo, track, e)
+        return _bootstrap_forecast()
+
+
+def _resolve_task_and_track(work_item_id: str, repo: str | None):
+    """Best-effort (task_id, repo, track) for ``work_item_id`` from the DB.
+
+    A backlog issue has no task row yet -> ``(None, repo, 'full')``. never-raise.
+    """
+    task_id = None
+    track = "full"
+    try:
+        from . import db
+        task = db.get_task_by_work_item_id(work_item_id)
+        if task:
+            task_id = task.get("id")
+            track = (task.get("track") or "full") or "full"
+            if not repo:
+                repo = task.get("repo")
+    except Exception as e:  # noqa: BLE001
+        logger.warning("estimator._resolve_task_and_track error for %s: %s", work_item_id, e)
+    return task_id, (repo or ""), track
+
+
+# ---------------------------------------------------------------------------
+# Producer — compute + persist + publish (the extension boundary D1)
+# ---------------------------------------------------------------------------
+def estimate(work_item_id: str, issue: dict | None = None, repo: str = None,
+             source: str = "status") -> dict:
+    """Produce + persist + publish a forecast for ``work_item_id`` (ADR-001 D5..D8).
+
+    Returns ``{forecast_tokens, forecast_seconds, forecast_cost_usd, story_points}``.
+    Side effects (all best-effort / never-raise): UPSERT into ``task_estimates``
+    (idempotent re-estimation by work_item_id), Plane write of the forecast story-points
+    to ``estimate_point`` + a forecast comment, and a Telegram-card refresh. The
+    ``issue`` payload is accepted for forward-compat (description signals, D2) but the
+    v1 heuristic keys only on repo+track. Callers (``handle_estimate`` / the optional
+    endpoints) assume ``applies(repo)`` has already passed.
+
+    Never raises: any internal error -> a safe bootstrap forecast is still returned.
+    """
+    task_id, repo, track = _resolve_task_and_track(work_item_id, repo)
+    forecast = _forecast(repo, track)
+    _COUNTERS["forecasts"] += 1
+
+    # D7: persist the forecast (UPSERT by work_item_id) — durable & idempotent.
+    try:
+        from . import db
+        db.record_estimate(
+            work_item_id=work_item_id,
+            repo=repo or None,
+            task_id=task_id,
+            forecast_tokens=forecast["forecast_tokens"],
+            forecast_seconds=forecast["forecast_seconds"],
+            forecast_cost_usd=forecast["forecast_cost_usd"],
+            forecast_story_points=forecast["story_points"],
+            source=source,
+        )
+    except Exception as e:  # noqa: BLE001 - never-raise
+        logger.warning("estimator.estimate: persist failed for %s: %s", work_item_id, e)
+
+    # D6/D8: Plane write (estimate_point + comment) — best-effort / fail-safe.
+    try:
+        from . import plane_sync
+        if plane_sync.set_issue_estimate_point(work_item_id, forecast["story_points"]):
+            _COUNTERS["plane_writes"] += 1
+        plane_sync.add_comment(
+            work_item_id, _comment_text(forecast), author="stream"
+        )
+    except Exception as e:  # noqa: BLE001 - never-raise
+        logger.warning("estimator.estimate: Plane write failed for %s: %s", work_item_id, e)
+
+    # D8: refresh the Telegram card so the «Оценка» line appears (if a task exists).
+    if task_id is not None:
+        try:
+            from . import notifications
+            notifications.update_task_tracker(int(task_id))
+        except Exception as e:  # noqa: BLE001 - never-raise
+            logger.warning("estimator.estimate: card refresh failed for %s: %s", work_item_id, e)
+
+    logger.info(
+        "estimator: %s -> forecast cost=$%.2f time=%ss tokens=%s SP=%s (track=%s, src=%s)",
+        work_item_id, forecast["forecast_cost_usd"], forecast["forecast_seconds"],
+        forecast["forecast_tokens"], forecast["story_points"], track, source,
+    )
+    return forecast
+
+
+# ---------------------------------------------------------------------------
+# Fact on done (D9)
+# ---------------------------------------------------------------------------
+def record_actual_on_done(task_id: int, repo: str, work_item_id: str) -> bool:
+    """ORCH-020 (ADR-001 D9): on task completion, derive the FACT from usage and write
+    it to Plane ``point`` + the ledger. Best-effort / never-raise; gated by
+    ``applies(repo)`` so non-self repos are a no-op. Returns True iff a fact was written.
+
+    Does NOT overwrite the forecast (``estimate_point``) — only the int ``point`` field
+    and the actual_* columns (AC-4). Does NOT influence the stage transition (the
+    врезка runs AFTER the decision to move to done).
+    """
+    try:
+        if not applies(repo):
+            return False
+        if not work_item_id:
+            return False
+        from . import db, usage
+        summary = usage.task_usage_summary(int(task_id)) if task_id is not None else {}
+        actual_tokens = int(summary.get("total_in", 0) or 0) + int(summary.get("total_out", 0) or 0)
+        actual_cost = float(summary.get("total_cost", 0.0) or 0.0)
+        actual_seconds = _task_wall_seconds(task_id)
+        actual_sp = story_points_for(actual_cost)
+        db.set_actual(
+            work_item_id,
+            actual_tokens=actual_tokens,
+            actual_seconds=actual_seconds,
+            actual_cost_usd=round(actual_cost, 4),
+            actual_story_points=actual_sp,
+            task_id=task_id,
+        )
+        _COUNTERS["actuals"] += 1
+        try:
+            from . import plane_sync
+            plane_sync.set_issue_point(work_item_id, actual_sp)
+        except Exception as e:  # noqa: BLE001 - best-effort Plane write
+            logger.warning("estimator.record_actual_on_done: Plane point write failed for %s: %s",
+                           work_item_id, e)
+        logger.info(
+            "estimator: %s done -> fact cost=$%.2f time=%ss tokens=%s SP=%s",
+            work_item_id, actual_cost, actual_seconds, actual_tokens, actual_sp,
+        )
+        return True
+    except Exception as e:  # noqa: BLE001 - never-raise: done must not crash
+        logger.warning("estimator.record_actual_on_done error for %s: %s", work_item_id, e)
+        return False
+
+
+def _task_wall_seconds(task_id: int) -> int | None:
+    """Wall-time (updated_at - created_at) of a task, capped at ``estimator_wall_cap_s``.
+    None on any error / missing row. never-raise."""
+    try:
+        from . import db
+        conn = db.get_db()
+        try:
+            row = conn.execute(
+                "SELECT CAST(strftime('%s', updated_at) - strftime('%s', created_at) "
+                "AS INTEGER) AS wall_s FROM tasks WHERE id = ?",
+                (int(task_id),),
+            ).fetchone()
+        finally:
+            conn.close()
+        if not row or row["wall_s"] is None:
+            return None
+        wall = int(row["wall_s"])
+        if wall < 0:
+            return None
+        cap = int(getattr(settings, "estimator_wall_cap_s", 86400) or 0)
+        return min(wall, cap) if cap > 0 else wall
+    except Exception as e:  # noqa: BLE001
+        logger.warning("estimator._task_wall_seconds error for %s: %s", task_id, e)
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Rendering helpers (Plane comment + Telegram card line)
+# ---------------------------------------------------------------------------
+def _comment_text(forecast: dict) -> str:
+    """Plane comment body for a forecast (cost/time/tokens/story points)."""
+    try:
+        from .usage import fmt_tokens, fmt_cost, fmt_duration
+        cost = fmt_cost(forecast.get("forecast_cost_usd", 0.0))
+        secs = forecast.get("forecast_seconds", 0)
+        time_s = fmt_duration(secs) if secs else "?"
+        toks = fmt_tokens(forecast.get("forecast_tokens", 0))
+        sp = forecast.get("story_points", "?")
+    except Exception:  # noqa: BLE001 - never let rendering break the flow
+        cost = f"${forecast.get('forecast_cost_usd', 0.0):.2f}"
+        time_s = str(forecast.get("forecast_seconds", "?"))
+        toks = str(forecast.get("forecast_tokens", "?"))
+        sp = forecast.get("story_points", "?")
+    return (
+        f"\U0001f4ca Оценка задачи: "
+        f"~{cost} · ~{time_s} · ~{toks} токенов · "
+        f"сложность {sp} SP"
+    )
+
+
+def card_line(work_item_id: str) -> str | None:
+    """ORCH-020 (D8): the «Оценка» line for the Telegram card (time · tokens · cost),
+    read from ``task_estimates`` by work_item_id. None when there is no forecast (the
+    line is then omitted) or on ANY error. never-raise — the card must always render.
+    """
+    try:
+        if not work_item_id:
+            return None
+        from . import db
+        from .usage import fmt_tokens, fmt_cost, fmt_duration
+        row = db.get_estimate(work_item_id)
+        if not row or row.get("forecast_story_points") is None:
+            return None
+        cost = fmt_cost(row.get("forecast_cost_usd") or 0.0)
+        secs = row.get("forecast_seconds")
+        time_s = fmt_duration(secs) if secs else "?"
+        toks = fmt_tokens(row.get("forecast_tokens") or 0)
+        sp = row.get("forecast_story_points")
+        return (
+            f"\U0001f4ca Оценка: {time_s} · "
+            f"{toks} · {cost} · {sp} SP"
+        )
+    except Exception as e:  # noqa: BLE001 - never-raise (card must render)
+        logger.warning("estimator.card_line error for %s: %s", work_item_id, e)
+        return None
+
+
+def note_backlog_return() -> None:
+    """Bump the backlog-return counter (called by handle_estimate after set_issue_backlog)."""
+    _COUNTERS["backlog_returns"] += 1
+
+
+# ---------------------------------------------------------------------------
+# Observability snapshot for GET /queue (D11)
+# ---------------------------------------------------------------------------
+def snapshot() -> dict:
+    """Read-only estimator summary for GET /queue (additive block). never-raise."""
+    try:
+        enabled = bool(getattr(settings, "estimator_enabled", False))
+    except Exception:  # noqa: BLE001
+        enabled = False
+    try:
+        repos_cfg = getattr(settings, "estimator_repos", "") or ""
+    except Exception:  # noqa: BLE001
+        repos_cfg = ""
+    out = {
+        "enabled": enabled,
+        "repos": repos_cfg,
+        "min_samples": getattr(settings, "estimator_min_samples", 3),
+        "sp_cost_thresholds": getattr(settings, "estimator_sp_cost_thresholds", ""),
+        "counters": dict(_COUNTERS),
+    }
+    try:
+        from . import db
+        out["ledger"] = db.estimates_snapshot(limit=10)
+    except Exception as e:  # noqa: BLE001 - never crash the endpoint
+        logger.warning("estimator.snapshot ledger error: %s", e)
+        out["ledger"] = {"total": 0, "with_actual": 0, "recent": []}
+    return out

src/main.py

@@ -269,6 +269,7 @@ async def queue():
     from . import transition_lease
     from . import staging_runner
     from . import test_runner
+    from . import estimator
     from .disk_watchdog import disk_watchdog
     from .build_cache_pruner import build_cache_pruner
     return {
@@ -327,6 +328,11 @@ async def queue():
         # tool_error/deferred counters, so a code-fail FAIL is distinguishable from an
         # infra tool-error. Additive block; never-raise.
         "test_runner": test_runner.snapshot(),
+        # ORCH-020 (FR-T10 / AC-9): task-estimation observability (read-only) —
+        # kill-switch, scope, story-point thresholds + forecast/Plane-write/backlog-
+        # return/fact counters + a light ledger summary (total / with-actual / recent).
+        # Additive block; never-raise.
+        "estimator": estimator.snapshot(),
         # ORCH-098 (FR-4 / AC-4): lessons-journal observability (read-only) —
         # kill-switch + counts by type/status + last N lessons. Additive block;
         # never-raise (snapshot() returns {"enabled": ...} minimum on error).
@@ -586,6 +592,52 @@ async def bug_fast_track_escalate(work_item: str = ""):
     return {"ok": True, "work_item": work_item, "track": "full", "was": prev_track}
 
 
+# ---------------------------------------------------------------------------
+# ORCH-020 (TRZ §4 / AC-7, ADR-001 D12): OPTIONAL programmatic estimation endpoints —
+# a convenience / diagnostics path, NOT the main trigger (the main path is the «Оценка»
+# Plane status; bulk = Plane multi-select). They reuse the SAME core estimator.estimate
+# (UPSERT + estimate_point + comment + card), so the result is identical to the status
+# trigger. With the kill-switch off / out of scope they are an inert no-op. never-raise.
+# ---------------------------------------------------------------------------
+@app.post("/estimate")
+async def estimate_one(work_item: str = ""):
+    """ORCH-020: produce/refresh a forecast for one task by work_item id, then return
+    it to Backlog (mirror of the «Оценка» status trigger). Idempotent (UPSERT). Returns
+    the forecast or ``{"enabled": false}`` / an error dict."""
+    from . import estimator, db
+    from .plane_sync import set_issue_backlog
+    if not work_item or not work_item.strip():
+        return {"ok": False, "error": "missing 'work_item'", "work_item": work_item}
+    work_item = work_item.strip()
+    task = db.get_task_by_work_item_id(work_item)
+    repo = (task or {}).get("repo") or ""
+    if not estimator.applies(repo):
+        return {"ok": False, "enabled": False, "reason": "estimator not applicable",
+                "repo": repo, "work_item": work_item}
+    if not estimator.should_estimate(task):
+        return {"ok": False, "error": "task has an active job (anti-disruption)",
+                "work_item": work_item}
+    forecast = estimator.estimate(work_item, None, repo, "api")
+    try:
+        set_issue_backlog(work_item)
+        estimator.note_backlog_return()
+    except Exception:  # noqa: BLE001 - best-effort
+        pass
+    return {"ok": True, "work_item": work_item, "forecast": forecast}
+
+
+@app.get("/estimate")
+async def estimate_read(work_item: str = ""):
+    """ORCH-020: read the current forecast vs fact from the task_estimates ledger."""
+    from . import db
+    if not work_item or not work_item.strip():
+        return {"ok": False, "error": "missing 'work_item'", "work_item": work_item}
+    row = db.get_estimate(work_item.strip())
+    if not row:
+        return {"ok": True, "work_item": work_item.strip(), "estimate": None}
+    return {"ok": True, "work_item": work_item.strip(), "estimate": row}
+
+
 # ---------------------------------------------------------------------------
 # ORCH-098 (FR-4 / FR-5, ADR-001 D5): machine lessons-journal endpoints.
 # Read-only fetch + manual record + re-classify. All never-raise; with the

src/notifications.py

@@ -479,6 +479,20 @@ def render_task_tracker(task_id: int) -> str:
     status_line = f"\U0001f4cd {_esc(status_label)}"
     lines = [header, status_line, bar]
 
+    # ORCH-020 (ADR-001 D8): the «Оценка» forecast line (time · tokens · cost · SP),
+    # read from task_estimates by work_item_id. Omitted when there is no forecast for
+    # the task; the helper is never-raise, so a missing/broken estimate never breaks the
+    # card. The data slots are already escaped inside estimator.card_line via the usage
+    # fmt_* helpers (numeric output only — no markup), keeping the "one card per task"
+    # invariant intact.
+    try:
+        from . import estimator
+        est_line = estimator.card_line(work_item_id)
+        if est_line:
+            lines.append(est_line)
+    except Exception:
+        pass
+
     # ORCH-026 (B-4): waiting-line for a task blocked by an unfinished declared
     # dependency. Shows WHAT the task is waiting on ("⏳ ждёт ORCH-NNN"),
     # so the single tracker card (invariant preserved) makes the wait visible.

src/plane_sync.py

@@ -156,6 +156,14 @@ _PLANE_NAME_TO_KEY: dict[str, str] = {
     # (no UUID, no KeyError, no blind cancel). Create a STOP status with the
     # `cancelled` group on the board to enable it (07-infra-requirements.md).
     "STOP": "stop",
+    # ORCH-020: dedicated operator "Оценка" status — the task-estimation trigger, the
+    # third member of the action-status family (STOP / Confirm Deploy). Like them it is
+    # INTENTIONALLY ABSENT from _DEFAULT_STATES (fail-closed): a board without the
+    # status resolves `estimate` to None via .get -> the estimate branch never activates
+    # (no UUID, no KeyError, no estimation). Its Plane group must be backlog/unstarted
+    # (NEVER completed/cancelled — that would false-trip the ORCH-068 terminal detect);
+    # see ORCH-020/07-infra-requirements.md.
+    "Оценка": "estimate",
     # ORCH-066: meaningful per-stage / human-input statuses (layer B).
     "To Analyse":               "to_analyse",
     "Analysis":                 "analysis",
@@ -955,6 +963,23 @@ def set_issue_in_progress(work_item_id: str, project_id: str = None):
     _set_issue_state_direct(work_item_id, state_id, project_id)
 
 
+def set_issue_backlog(work_item_id: str, project_id: str = None):
+    """ORCH-020 (ADR-001 D6): return the issue to the terminal-of-estimation Backlog.
+
+    Used by ``handle_estimate`` after the forecast is written, so the «Оценка» status
+    is a transient backlog-side gesture (the issue does not stick in it). The `backlog`
+    key already exists in ``_DEFAULT_STATES`` / ``_PLANE_NAME_TO_KEY``. Anti-loop: the
+    Backlog UUID matches NO trigger branch in ``handle_issue_updated`` (stop /
+    to_analyse / confirm_deploy / approved / rejected / estimate) -> the inbound
+    "state -> Backlog" webhook is a no-op echo. never-raise (via
+    ``_set_issue_state_direct``); best-effort — a failed status write does not drop the
+    already-persisted forecast.
+    """
+    project_id = _resolve_project_id(work_item_id, project_id)
+    state_id = get_project_states(project_id)["backlog"]
+    _set_issue_state_direct(work_item_id, state_id, project_id)
+
+
 def set_issue_analysis(work_item_id: str, project_id: str = None):
     """ORCH-066: set issue to 'Analysis' — analyst is working (start / resume).
 
@@ -1079,6 +1104,125 @@ def _set_issue_state_direct(work_item_id: str, state_id: str, project_id: str =
         logger.error(f"Failed to update Plane state for {work_item_id}: {e}")
 
 
+# ---------------------------------------------------------------------------
+# ORCH-020 (ADR-001 D6): task-estimation Plane writes. The forecast story-points go
+# to the estimate-system FK field `estimate_point`; the FACT goes to the legacy int
+# field `point` (robust — independent of the estimate-system config). All best-effort
+# / fail-safe (NFR-7): a missing estimate-system / unknown value / absent field / 4xx
+# -> skip + log, never a crash. All routed through the ORCH-117 write-guard.
+# ---------------------------------------------------------------------------
+# Per-project estimate-points cache (mirrors _STATES_CACHE / ORCH-068 TTL self-heal).
+_ESTIMATE_POINTS_CACHE: dict[str, dict] = {}
+
+
+def _patch_issue_fields(work_item_id: str, fields: dict, project_id: str = None) -> bool:
+    """PATCH arbitrary issue fields (e.g. {"point": 3}) under the ORCH-117 guard.
+
+    Returns True on a successful 2xx, False otherwise (guard block / issue not found /
+    network / non-2xx). never-raise.
+    """
+    project_id = _resolve_project_id(work_item_id, project_id)
+    if not _guard_allows_write(work_item_id, project_id, plane_write_guard.OP_STATE):
+        return False
+    if not fields:
+        return False
+    issue_id = find_issue_id(work_item_id, project_id)
+    if not issue_id:
+        logger.warning(f"Issue not found in Plane for {work_item_id}, skipping field PATCH")
+        return False
+    url = f"{PLANE_BASE}/workspaces/{WORKSPACE}/projects/{project_id}/issues/{issue_id}/"
+    try:
+        resp = httpx.patch(url, headers=PLANE_HEADERS, json=fields, timeout=10)
+        resp.raise_for_status()
+        logger.info(f"Plane: {work_item_id} fields {list(fields)} patched")
+        return True
+    except Exception as e:  # noqa: BLE001 - best-effort, never-raise
+        logger.warning(f"Failed to PATCH fields {list(fields)} for {work_item_id}: {e}")
+        return False
+
+
+def get_project_estimate_points(project_id: str) -> dict[int, str]:
+    """ORCH-020 (ADR-001 D6): resolve {point_value -> estimate_point UUID} for a project.
+
+    Net-new Plane integration: GET project -> active `estimate` id -> GET its
+    estimate-points -> map the numeric value (1/2/3/5/8) to the point UUID. TTL-cached
+    per project (mirrors get_project_states / ORCH-068). Any failure / missing
+    estimate-system -> ``{}`` (best-effort: the caller then skips the estimate_point
+    write, NFR-7). never-raise.
+    """
+    if not project_id:
+        return {}
+    cached = _ESTIMATE_POINTS_CACHE.get(project_id)
+    if cached is not None and _cache_record_fresh(cached):
+        return cached["points"]
+    points: dict[int, str] = {}
+    try:
+        proj_url = f"{PLANE_BASE}/workspaces/{WORKSPACE}/projects/{project_id}/"
+        presp = httpx.get(proj_url, headers=PLANE_HEADERS, timeout=10)
+        presp.raise_for_status()
+        estimate_id = presp.json().get("estimate")
+        if estimate_id:
+            ep_url = (
+                f"{PLANE_BASE}/workspaces/{WORKSPACE}/projects/{project_id}/"
+                f"estimates/{estimate_id}/estimate-points/"
+            )
+            eresp = httpx.get(ep_url, headers=PLANE_HEADERS, timeout=10)
+            eresp.raise_for_status()
+            body = eresp.json()
+            items = body.get("results", body) if isinstance(body, dict) else body
+            for item in (items or []):
+                uid = item.get("id", "")
+                val = item.get("value", item.get("key"))
+                try:
+                    ival = int(float(val))
+                except (TypeError, ValueError):
+                    continue
+                if uid:
+                    points[ival] = uid
+    except Exception as e:  # noqa: BLE001 - best-effort, never-raise
+        logger.warning(f"get_project_estimate_points failed for {project_id}: {e}")
+        return {}
+    _ESTIMATE_POINTS_CACHE[project_id] = {"points": points, "ts": time.monotonic()}
+    return points
+
+
+def set_issue_estimate_point(work_item_id: str, value, project_id: str = None) -> bool:
+    """ORCH-020 (ADR-001 D6): write the FORECAST story-points to the issue
+    ``estimate_point`` FK field (resolved to its point UUID via the estimate-system).
+
+    best-effort / fail-safe (NFR-7): if the estimate-system is not configured, the
+    value is outside it, or the resolve/PATCH fails -> skip + log (the durable forecast
+    in task_estimates is unaffected). Returns True iff the PATCH succeeded.
+    """
+    project_id = _resolve_project_id(work_item_id, project_id)
+    try:
+        ival = int(value)
+    except (TypeError, ValueError):
+        logger.warning(f"set_issue_estimate_point: non-int value {value!r} for {work_item_id}")
+        return False
+    points = get_project_estimate_points(project_id)
+    uid = points.get(ival)
+    if not uid:
+        logger.info(
+            f"set_issue_estimate_point: estimate-system has no point {ival} for "
+            f"{work_item_id} (estimate-system unconfigured/partial); skipping (best-effort)"
+        )
+        return False
+    return _patch_issue_fields(work_item_id, {"estimate_point": uid}, project_id)
+
+
+def set_issue_point(work_item_id: str, value, project_id: str = None) -> bool:
+    """ORCH-020 (ADR-001 D6): write the FACT story-points to the legacy integer issue
+    field ``point`` (robust — does not depend on the estimate-system). Returns True iff
+    the PATCH succeeded; never-raise / best-effort."""
+    try:
+        ival = int(value)
+    except (TypeError, ValueError):
+        logger.warning(f"set_issue_point: non-int value {value!r} for {work_item_id}")
+        return False
+    return _patch_issue_fields(work_item_id, {"point": ival}, project_id)
+
+
 def notify_stage_change(work_item_id: str, old_stage: str, new_stage: str, agent: str = None, project_id: str = None):
     """Notify Plane about stage transition with links."""
     project_id = _resolve_project_id(work_item_id, project_id)

src/stage_engine.py

@@ -544,6 +544,20 @@ def advance_stage(
             except Exception as e:  # noqa: BLE001 - defensive
                 logger.warning(f"Task {task_id}: merge-lease release on done failed: {e}")
 
+        # ORCH-020 (ADR-001 D9): on completion, record the FACT (cost/time/tokens ->
+        # story points) from usage and write it to Plane `point` + the task_estimates
+        # ledger. Thin best-effort врезка AFTER the terminal decision — it does NOT
+        # influence the transition (STAGE_TRANSITIONS / check_deploy_status /
+        # machine-verdict untouched) and never overwrites the forecast `estimate_point`.
+        # estimator.record_actual_on_done is gated by applies(repo) (non-self repos ->
+        # no-op) and is never-raise: done must never crash on an estimator error.
+        if next_stage == "done" and work_item_id:
+            try:
+                from . import estimator
+                estimator.record_actual_on_done(task_id, repo, work_item_id)
+            except Exception as e:  # noqa: BLE001 - never-raise: done must not crash
+                logger.warning(f"Task {task_id}: estimate fact-on-done failed: {e}")
+
         # --- Launch the next agent (ORCH-4 fix: current_stage, not next) -----
         next_agent = get_agent_for_stage(current_stage)
         # ORCH-019 (ADR-001 D3): get_agent_for_stage('analysis') is 'architect'; for a

src/webhooks/plane.py

@@ -166,9 +166,18 @@ async def handle_issue_updated(data: dict, project_id: str = ""):
     # branch never activates, exactly like confirm_deploy). Checked FIRST so a STOP
     # is never aliased by to_analyse/approved/rejected.
     stop_state = proj_states.get("stop")
+    # ORCH-020: dedicated operator "Оценка" status -> task estimation (forecast +
+    # return to Backlog). fail-closed via .get (no UUID on a board without the status
+    # -> None -> branch never activates, exactly like stop/confirm_deploy). Placed right
+    # after `stop` (D4) — mutual exclusion is guaranteed by the DISTINCT status UUID,
+    # not the order; the estimate gesture never aliases stop/to_analyse/confirm_deploy/
+    # approved/rejected.
+    estimate_state = proj_states.get("estimate")
     # ORCH-066: start/resume trigger is `To Analyse` (human entry-point).
     if stop_state and new_state == stop_state:
         await handle_stop(data, project_id)
+    elif estimate_state and new_state == estimate_state:
+        await handle_estimate(data, project_id)
     elif new_state == proj_states["to_analyse"]:
         await handle_status_start(data, project_id)
     elif confirm_state and new_state == confirm_state:
@@ -258,6 +267,86 @@ async def handle_stop(data: dict, project_id: str = ""):
         logger.error(f"STOP handling failed for task {task_id}: {e}")
 
 
+async def handle_estimate(data: dict, project_id: str = ""):
+    """ORCH-020: a human flipped the issue to the dedicated «Оценка» status — produce a
+    task-size forecast (cost / time / tokens / story points), then return the issue to
+    Backlog.
+
+    The estimator core is synchronous and makes network Plane calls, so it is run off
+    the event loop via ``asyncio.to_thread`` (mirror of ``handle_stop``). Guard chain
+    (each a no-op-with-log on failure, never-raise — NFR-2):
+      1. ``estimator.applies(repo)`` — kill-switch + scope, LOCAL and FIRST (no network
+         when the flag is off);
+      2. anti-disruption (BR-T6): an issue whose pipeline-task has an ACTIVE job is NOT
+         yanked into a re-estimate (``estimator.should_estimate``). A backlog issue (no
+         task) or a terminal/idle task is fair game.
+    Then: ``estimator.estimate(...)`` (forecast + persist + Plane/card) -> best-effort
+    ``set_issue_backlog`` (D5 anti-loop: Backlog matches no trigger branch -> the
+    inbound state->Backlog webhook is a no-op echo). Contract is never-raise.
+    """
+    import asyncio
+    from .. import estimator
+
+    plane_id = str(data.get("id") or "")
+    if not plane_id:
+        logger.info("«Оценка» webhook without issue id, ignoring (no-op)")
+        return
+
+    # Resolve repo / prefix from the project registry (the issue may have NO task yet —
+    # it can sit in the backlog at estimate time).
+    proj = get_project_by_plane_id(project_id) or get_project_by_plane_id(
+        data.get("project") or data.get("project_id") or ""
+    )
+    repo = proj.repo if proj else ""
+
+    # Guard 1: kill-switch / scope (local, network-free, FIRST).
+    if not estimator.applies(repo):
+        logger.info(
+            f"«Оценка» for {plane_id} (repo={repo}) but estimation is not applicable "
+            f"(kill-switch off / out of scope); no-op"
+        )
+        return
+
+    task = get_task_by_plane_id(plane_id)
+
+    # Guard 2: anti-disruption — never yank an in-flight task back to Backlog.
+    if not estimator.should_estimate(task):
+        logger.info(
+            f"«Оценка» for {plane_id} but the task has an active job (in-flight); "
+            f"no-op (anti-disruption, BR-T6)"
+        )
+        return
+
+    # Resolve the work_item_id: from the task if it exists, else derive it the SAME way
+    # start_pipeline does (Plane sequence_id -> PREFIX-NNN) so the backlog forecast links
+    # to the task once it starts; fall back to the raw plane_id if Plane is unavailable.
+    work_item_id = (task or {}).get("work_item_id") or ""
+    if not work_item_id:
+        try:
+            from ..plane_sync import fetch_issue_sequence_id
+            seq = fetch_issue_sequence_id(plane_id, project_id)
+            if seq is not None and proj is not None:
+                work_item_id = f"{proj.work_item_prefix}-{seq:03d}"
+        except Exception as e:
+            logger.warning(f"«Оценка»: sequence derive failed for {plane_id}: {e}")
+    if not work_item_id:
+        work_item_id = plane_id
+
+    logger.info(f"«Оценка» status for {plane_id} -> estimating {work_item_id} (repo={repo})")
+    try:
+        await asyncio.to_thread(estimator.estimate, work_item_id, data, repo, "status")
+    except Exception as e:  # never-raise: the webhook flow must not crash
+        logger.error(f"Estimation failed for {work_item_id}: {e}")
+
+    # Auto-return to Backlog (best-effort; the forecast is already persisted — FR-T5).
+    try:
+        from ..plane_sync import set_issue_backlog
+        await asyncio.to_thread(set_issue_backlog, work_item_id, project_id)
+        estimator.note_backlog_return()
+    except Exception as e:  # never-raise
+        logger.error(f"«Оценка»: return-to-Backlog failed for {work_item_id}: {e}")
+
+
 async def handle_status_start(data: dict, project_id: str = ""):
     """An issue moved into In Progress.
 
@@ -657,8 +746,12 @@ async def start_pipeline(data: dict, project_id: str = ""):
     # process-wide lock. If the F-2 reconciler and this live webhook race on the
     # same plane_id, exactly one wins (created=True); the loser sees the existing
     # task and returns WITHOUT creating a second branch / worktree / analyst job.
+    # ORCH-119 (FR-3 / AC-3): persist `description` DURABLE inside the same atomic
+    # INSERT (mirror of `title`) so the deferred branch cut (path B, ORCH-088 — dominates
+    # on self-hosting) can read it from the tasks row at claim time and render the real
+    # request text into 00-business-request.md instead of the hardcoded `TBD`.
     task_row, created = create_task_atomic(
-        plane_id, work_item_id, repo, branch, "analysis", name
+        plane_id, work_item_id, repo, branch, "analysis", name, description
     )
     if not created:
         logger.info(
@@ -726,8 +819,10 @@ async def start_pipeline(data: dict, project_id: str = ""):
             return
 
         # Create initial docs structure via Gitea API (create file)
+        # ORCH-119 (FR-2 / AC-2): direct path A — pass the source-backed `description`
+        # so the artifact is created with the real request text in one call.
         try:
-            await _create_initial_docs(repo, branch, work_item_id, name)
+            await _create_initial_docs(repo, branch, work_item_id, name, description)
         except Exception as e:
             logger.error(f"Failed to create initial docs: {e}")
     else:
@@ -934,15 +1029,59 @@ async def _create_gitea_branch(repo: str, branch: str):
         logger.info(f"Created branch '{branch}' in {owner}/{repo}")
 
 
-async def _create_initial_docs(repo: str, branch: str, work_item_id: str, name: str):
-    """Create initial business request doc in the feature branch."""
+# ORCH-119 (FR-4 / AC-4): explicit safe marker used when the source description is
+# empty / whitespace / None / unreadable — NOT the historic bare `TBD` bug.
+_BUSINESS_REQUEST_FALLBACK = "_(описание отсутствует в источнике)_"
+
+
+def _render_business_request(
+    work_item_id: str, name: str, description: str | None
+) -> str:
+    """ORCH-119 (FR-1 / BR-1): render the body of ``00-business-request.md`` from the
+    source-backed Plane-issue ``description``.
+
+    Pure & network-free so it is unit-testable without Gitea (TC-01/TC-02/TC-06). The
+    Description section carries the ACTUAL request text plain-text and verbatim —
+    multi-line content and markdown special chars are preserved (the doc is
+    informational and NOT gate-parsed, NFR-2); only surrounding whitespace is trimmed
+    for the emptiness check. Empty / whitespace / None / any failure degrades to an
+    explicit safe marker (``_BUSINESS_REQUEST_FALLBACK``) instead of the historic bare
+    ``TBD`` (FR-4 / AC-4); never raises. The header (``# Business Request: {name}``)
+    and ``Work Item ID`` are unchanged.
+    """
+    try:
+        body = (description or "").strip()
+        if not body:
+            body = _BUSINESS_REQUEST_FALLBACK
+    except Exception:  # noqa: BLE001 - never let rendering break task creation
+        body = _BUSINESS_REQUEST_FALLBACK
+    return (
+        f"# Business Request: {name}\n\n"
+        f"Work Item ID: {work_item_id}\n\n"
+        f"## Description\n\n{body}\n"
+    )
+
+
+async def _create_initial_docs(
+    repo: str, branch: str, work_item_id: str, name: str,
+    description: str | None = None,
+):
+    """Create initial business request doc in the feature branch.
+
+    ORCH-119: the Description section now carries the source-backed Plane-issue
+    ``description`` (rendered via ``_render_business_request``) instead of the historic
+    hardcoded ``TBD``. ``description`` is additive with a default so existing callers /
+    a re-claim stay backward-compatible; empty/None degrades to a safe marker.
+    Idempotent: Gitea 422 (file already exists) -> no-op, the previously written body
+    is NOT overwritten (AC-6 / TC-06).
+    """
     owner = settings.gitea_owner
     file_path = f"docs/work-items/{work_item_id}/00-business-request.md"
     url = f"{settings.gitea_url}/api/v1/repos/{owner}/{repo}/contents/{file_path}"
     headers = {"Authorization": f"token {settings.gitea_token}"}
 
     import base64
-    content = f"# Business Request: {name}\n\nWork Item ID: {work_item_id}\n\n## Description\n\nTBD\n"
+    content = _render_business_request(work_item_id, name, description)
     encoded = base64.b64encode(content.encode()).decode()
 
     payload = {

tests/test_bundled_setup_doc.py

@@ -244,17 +244,18 @@ def test_every_env_token_in_doc_exists_in_canons():
 
 
 def test_status_count_claim_matches_plane_sync():
-    """«22 статуса» держится фактическим маппингом src/plane_sync.py (AC-7:
-    сверка импортом, не строковой копией)."""
+    """«23 статуса» держится фактическим маппингом src/plane_sync.py (AC-7:
+    сверка импортом, не строковой копией). ORCH-020 добавил 23-й статус «Оценка»."""
     from src.plane_sync import _PLANE_NAME_TO_KEY
 
-    assert len(_PLANE_NAME_TO_KEY) == 22, (
+    assert len(_PLANE_NAME_TO_KEY) == 23, (
         "число статусов в plane_sync изменилось — обнови BUNDLED_SETUP.md §7 "
         "(и ONBOARDING.md §1)"
     )
     assert "Confirm Deploy" in _PLANE_NAME_TO_KEY
     assert "STOP" in _PLANE_NAME_TO_KEY
-    assert "22" in _doc_text(), "число статусов в BUNDLED_SETUP.md разъехалось с plane_sync"
+    assert "Оценка" in _PLANE_NAME_TO_KEY
+    assert "23" in _doc_text(), "число статусов в BUNDLED_SETUP.md разъехалось с plane_sync"
 
 
 # ---------------------------------------------------------------------------

tests/test_faq_stop_doc.py

@@ -0,0 +1,291 @@
+"""ORCH-108 (FR-6 / AC-1…AC-11): анти-дрейф контур пользовательского FAQ по STOP.
+
+Структурные проверки golden source `docs/operations/FAQ_STOP.md` (ADR-001 D3,
+образец — `tests/test_lite_setup_doc.py`): док существует и адресован пользователю
+(TC-01); присутствуют все 8 обязательных секций-якорей FR-2 (TC-02); несёт ключевые
+факты-«кирпичи» о последствиях STOP (TC-03), об отложенной отмене (TC-04), о том что
+STOP не откатывает прод-код (TC-05) и о перезапуске через «To Analyse» с нуля (TC-06);
+негативный скан запрещённых **утверждений** на уровне предложений, а НЕ голых подстрок
+(TC-07, ключевой нюанс D3 — иначе тест краснел бы на корректно отрицающих фразах);
+двусторонние перекрёстные ссылки витрина/обзор ⇄ FAQ ⇄ ADR ORCH-090 (TC-08);
+docs-only / детерминированность самого теста — без сети/LLM/subprocess (TC-09).
+
+Детерминировано: только парсинг файлов (read_text), без сети/LLM/subprocess.
+Поведение STOP в рантайме реализовано и протестировано в ORCH-090 — эта задача его
+НЕ меняет (docs-only), здесь проверяется лишь структурная целостность документации.
+"""
+
+import re
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+FAQ = REPO_ROOT / "docs/operations/FAQ_STOP.md"
+BUSINESS = REPO_ROOT / "docs/overview/business.md"
+TECH_PIPELINE = REPO_ROOT / "docs/overview/tech-pipeline.md"
+
+# Обязательные секции FR-2: распознаваемая (нормализованная, регистронезависимая)
+# подстрока заголовка `## ` — стабильный якорь, толерантный к полировке пунктуации.
+SECTION_ANCHORS: tuple[str, ...] = (
+    "что делает статус stop",                       # (1) назначение
+    "как отменить задачу",                          # (2) как отменить
+    "что происходит, когда я нажимаю stop",         # (3) пошагово
+    "сливается или деплоится",                      # (4) отложенная отмена
+    "откатит ли stop уже выложенный код",           # (5) не откатывает прод
+    "как перезапустить отменённую задачу",          # (6) перезапуск с нуля
+    "ничего не произошло",                          # (7) no-op причины
+    "где увидеть, что задача отменена",             # (8) где увидеть результат
+)
+
+
+# ---------------------------------------------------------------------------
+# helpers
+# ---------------------------------------------------------------------------
+def _faq_text() -> str:
+    assert FAQ.is_file(), "docs/operations/FAQ_STOP.md отсутствует (AC-1)"
+    text = FAQ.read_text(encoding="utf-8")
+    assert text.strip(), "FAQ_STOP.md пуст (AC-1)"
+    return text
+
+
+def _headers() -> list[str]:
+    """Нормализованные (lowercase) тексты markdown-заголовков `#`/`##`/…."""
+    return [
+        re.sub(r"^#+\s*", "", line).strip().lower()
+        for line in _faq_text().splitlines()
+        if line.lstrip().startswith("#")
+    ]
+
+
+def _body_sentences() -> list[str]:
+    """Предложения тела FAQ БЕЗ заголовков и без code-fence-блоков.
+
+    Заголовки этого FAQ — вопросы («Откатит ли STOP…?», «Что если…?») и по
+    построению не несут утверждений; негативный скан утверждений (TC-07)
+    исключает их, чтобы не краснеть на легитимных вопросах-якорях (D3/TR-3).
+    """
+    lines: list[str] = []
+    in_fence = False
+    for raw in _faq_text().splitlines():
+        stripped = raw.strip()
+        if stripped.startswith("```"):
+            in_fence = not in_fence
+            continue
+        if in_fence or stripped.startswith("#"):
+            continue
+        lines.append(raw)
+    body = " ".join(lines)
+    return [s.strip().lower() for s in re.split(r"[.!?\n]+", body) if s.strip()]
+
+
+_NEGATION = re.compile(r"\b(?:не|нет|никогда|нельзя|без)\b", re.IGNORECASE)
+
+# Опасные claim-триггеры (D3): ЕСЛИ предложение тела матчит триггер, оно ОБЯЗАНО
+# нести отрицание рядом, иначе это запрещённое FR-5 утверждение. Скан на уровне
+# предложений-утверждений, НЕ голых подстрок (заголовки-вопросы исключены).
+_CLAIM_TRIGGERS: tuple[tuple[str, re.Pattern[str]], ...] = (
+    # «STOP откатывает прод/влитый код» — должно встречаться только с отрицанием.
+    ("откат прод-кода", re.compile(r"откат\w*", re.IGNORECASE)),
+    # «можно продолжить отменённую с середины».
+    ("продолжить с середины", re.compile(r"продолж\w*[^.]{0,40}середин", re.IGNORECASE)),
+    # «STOP трогает main / делает force-push».
+    ("трогает main / force-push", re.compile(r"трога\w*|force[\s-]?push", re.IGNORECASE)),
+    # «STOP мгновенно убивает/прерывает идущий деплой/слияние».
+    (
+        "мгновенно убивает деплой",
+        re.compile(r"(?:мгновенн|немедленн)\w*[^.]{0,40}(?:убива|прерыва|деплой|слиян|выклад)", re.IGNORECASE),
+    ),
+)
+
+
+def _forbidden_claim_violations(sentences: list[str]) -> list[str]:
+    """Предложения, которые делают запрещённое утверждение без отрицания рядом."""
+    violations: list[str] = []
+    for name, trigger in _CLAIM_TRIGGERS:
+        for sent in sentences:
+            if trigger.search(sent) and not _NEGATION.search(sent):
+                violations.append(f"[{name}] {sent[:120]}")
+    return violations
+
+
+# ---------------------------------------------------------------------------
+# TC-01: FAQ существует, непустой, адресован пользователю (AC-1).
+# ---------------------------------------------------------------------------
+def test_faq_exists_user_oriented_with_h1():
+    text = _faq_text()
+    headers = _headers()
+    assert headers, "в FAQ_STOP.md нет ни одного заголовка"
+    assert "stop" in headers[0], f"H1 FAQ не про STOP: {headers[0]!r} (AC-1)"
+    # Вводный абзац «для кого/зачем» (тон пользовательский, без требования читать код).
+    intro = text.split("\n##", 1)[0].lower()
+    assert "для пользователя доски plane" in intro, (
+        "нет вводного абзаца «для кого» (AC-1) — FAQ должен адресоваться пользователю"
+    )
+    assert "не нужно" in intro and "код" in intro, (
+        "вводный абзац не фиксирует пользовательский тон «читать код не нужно» (AC-1)"
+    )
+
+
+# ---------------------------------------------------------------------------
+# TC-02: присутствуют все 8 обязательных секций-якорей FR-2 (AC-2).
+# ---------------------------------------------------------------------------
+def test_all_mandatory_sections_present():
+    headers_blob = " || ".join(_headers())
+    missing = [a for a in SECTION_ANCHORS if a not in headers_blob]
+    assert not missing, f"в FAQ_STOP.md отсутствуют обязательные секции FR-2 (AC-2): {missing}"
+
+
+# ---------------------------------------------------------------------------
+# TC-03: пошаговые последствия и сохранность docs (AC-3).
+# ---------------------------------------------------------------------------
+def test_step_consequences_and_docs_preserved():
+    low = _faq_text().lower()
+    bricks = {
+        "остановка агента": "останав",
+        "снятие job'ов": "job",
+        "удаление рабочей ветки": "ветк",
+        "удаление worktree": "worktree",
+        "переход в cancelled": "cancelled",
+        "уведомление telegram": "telegram",
+        "комментарий plane": "plane",
+        "docs сохраняются": "сохран",
+        "main/прод не трогаются": "main",
+    }
+    missing = [name for name, token in bricks.items() if token not in low]
+    assert not missing, f"раздел «что происходит» не несёт фактов (AC-3): {missing}"
+
+
+# ---------------------------------------------------------------------------
+# TC-04: критичное окно — отложенная отмена + main/прод не трогаются (AC-4).
+# ---------------------------------------------------------------------------
+def test_deferred_cancel_in_critical_window():
+    low = _faq_text().lower()
+    assert "отлож" in low, "нет факта отложенной отмены в критичном окне (AC-4)"
+    # «main/прод не трогаются» — явное отрицание рядом с критичным окном.
+    assert "не трогают" in low or "не трогаются" in low, (
+        "нет явного «main/прод не трогаются» (AC-4)"
+    )
+
+
+# ---------------------------------------------------------------------------
+# TC-05: STOP ≠ откат прод-кода — явный отрицательный ответ (AC-5).
+# ---------------------------------------------------------------------------
+def test_stop_does_not_revert_prod():
+    low = _faq_text().lower()
+    assert "не откатывает" in low, "нет явного «не откатывает» прод/влитый код (AC-5)"
+    assert "revert" in low or "отдельная задача" in low, (
+        "не сказано, что revert выложенного — отдельная задача (AC-5)"
+    )
+
+
+# ---------------------------------------------------------------------------
+# TC-06: перезапуск — «To Analyse» с нуля, без «продолжить с середины» (AC-6).
+# ---------------------------------------------------------------------------
+def test_restart_via_to_analyse_from_scratch():
+    text = _faq_text()
+    low = text.lower()
+    assert "to analyse" in low, "перезапуск не через «To Analyse» (AC-6)"
+    assert "с нуля" in low, "не сказано, что задача создаётся «с нуля» (AC-6)"
+    # «продолжить с середины» допустимо только в отрицающем предложении.
+    for sent in _body_sentences():
+        if "продолж" in sent and "середин" in sent:
+            assert _NEGATION.search(sent), (
+                f"обещание продолжить отменённую задачу с середины (AC-6): {sent[:120]!r}"
+            )
+
+
+# ---------------------------------------------------------------------------
+# TC-07a: «ничего не произошло» и идемпотентность — причины no-op (AC-7).
+# ---------------------------------------------------------------------------
+def test_noop_reasons_present():
+    low = _faq_text().lower()
+    assert "stop_status_enabled" in low and "stop_status_repos" in low, (
+        "не перечислены настройки отключения отмены (AC-7)"
+    )
+    assert "уже" in low and ("заверш" in low or "отмен" in low), (
+        "не описан идемпотентный no-op для уже терминальной задачи (AC-7)"
+    )
+
+
+# ---------------------------------------------------------------------------
+# TC-07b: негативный скан запрещённых утверждений (claim-level, не подстроки).
+# Инвариант D3: НЕ фолзит на верном FAQ; обязан краснеть на реально ложном (AC-9).
+# ---------------------------------------------------------------------------
+def test_no_forbidden_claims_in_real_faq():
+    violations = _forbidden_claim_violations(_body_sentences())
+    assert not violations, (
+        "FAQ_STOP.md содержит запрещённые FR-5 утверждения без отрицания (AC-9):\n"
+        + "\n".join(violations)
+    )
+
+
+def test_forbidden_claim_scanner_is_not_evergreen():
+    """Подсаженные ложные утверждения ОБЯЗАНЫ ловиться (паттерн ORCH-101/102:
+    сканер не может молча стать вечнозелёным). Зеркало
+    test_secret_heuristic_is_not_evergreen из test_lite_setup_doc.py."""
+    bad = [
+        "stop откатывает уже выложенный в прод код автоматически",
+        "отменённую задачу можно продолжить с середины конвейера",
+        "stop делает force-push в main для зачистки",
+        "stop мгновенно убивает идущий деплой на полпути",
+    ]
+    caught = _forbidden_claim_violations(bad)
+    assert len(caught) >= 4, f"сканер не ловит подсаженные ложные утверждения: {caught}"
+
+    # И обратно: корректные ОТРИЦАЮЩИЕ предложения НЕ должны ловиться (анти-TR-3).
+    good = [
+        "stop не откатывает код, уже влитый в main или выложенный в прод",
+        "отменённую задачу нельзя продолжить с середины",
+        "ветка main и прод никогда не трогаются",
+    ]
+    assert _forbidden_claim_violations(good) == [], (
+        "сканер ложно краснеет на корректно отрицающих предложениях (TR-3)"
+    )
+
+
+# ---------------------------------------------------------------------------
+# TC-08: двусторонние перекрёстные ссылки витрина/обзор ⇄ FAQ ⇄ ADR (AC-8).
+# ---------------------------------------------------------------------------
+def test_overview_docs_link_to_faq():
+    assert "FAQ_STOP.md" in BUSINESS.read_text(encoding="utf-8"), (
+        "docs/overview/business.md (Сценарий 6) не ссылается на FAQ_STOP.md (AC-8)"
+    )
+    assert "FAQ_STOP.md" in TECH_PIPELINE.read_text(encoding="utf-8"), (
+        "docs/overview/tech-pipeline.md (Отмена: STOP → cancelled) не ссылается на FAQ_STOP.md (AC-8)"
+    )
+
+
+def test_faq_links_back_to_overview_and_adr():
+    text = _faq_text()
+    assert "tech-pipeline.md" in text, "FAQ не ссылается на инженерный обзор (AC-8)"
+    assert "ORCH-090" in text and "ADR-001-stop-cancel-task.md" in text, (
+        "FAQ не ссылается на ADR ORCH-090 как источник истины (AC-8)"
+    )
+    # link-first: машинные детали не дублируются (даются ссылкой), а не копируются.
+    low = text.lower()
+    for machine_detail in ("тумбстон", "merge-lease", "_ensure_column"):
+        assert machine_detail not in low, (
+            f"FAQ дублирует машинную деталь {machine_detail!r} вместо ссылки (AC-8/D4)"
+        )
+
+
+# ---------------------------------------------------------------------------
+# TC-09: детерминированность самого теста — docs-only, без сети/LLM/subprocess.
+# ---------------------------------------------------------------------------
+def test_this_module_is_deterministic_offline():
+    """Самочек контракта D3: тест-модуль не импортирует сеть/subprocess/LLM и не
+    тянет рантайм src/ — читает только файлы docs/ (AC-10, AC-11)."""
+    # Скан реальных import-стейтментов по началу строки (а не подстрок — иначе
+    # тест ловил бы собственные строковые литералы из этого же списка).
+    banned = ("subprocess", "socket", "requests", "httpx", "urllib")
+    offenders: list[str] = []
+    for line in Path(__file__).read_text(encoding="utf-8").splitlines():
+        stripped = line.strip()
+        if not (stripped.startswith("import ") or stripped.startswith("from ")):
+            continue
+        module = stripped.split()[1].split(".", 1)[0]
+        if module in banned or module == "src":
+            offenders.append(stripped)
+    assert not offenders, (
+        f"анти-дрейф тест FAQ нарушает контракт детерминированности (сеть/subprocess/"
+        f"рантайм src): {offenders}"
+    )

tests/test_lite_setup_doc.py

@@ -367,17 +367,19 @@ def test_plane_canon_is_linked_not_forked():
 
 
 def test_status_count_claim_matches_plane_sync():
-    """Сверка импортом (не строковой копией): заявление дока «22 статуса»
-    держится фактическим маппингом src/plane_sync.py (нулевой дрейф, AC-6)."""
+    """Сверка импортом (не строковой копией): заявление дока «23 статуса»
+    держится фактическим маппингом src/plane_sync.py (нулевой дрейф, AC-6).
+    ORCH-020 добавил 23-й статус «Оценка» (триггер оценки задачи)."""
     from src.plane_sync import _PLANE_NAME_TO_KEY
 
-    assert len(_PLANE_NAME_TO_KEY) == 22, (
+    assert len(_PLANE_NAME_TO_KEY) == 23, (
         f"в plane_sync {_PLANE_NAME_TO_KEY and len(_PLANE_NAME_TO_KEY)} статусов — "
         "обнови число и раздел §5 LITE_SETUP.md (и ONBOARDING.md §1)"
     )
     assert "Confirm Deploy" in _PLANE_NAME_TO_KEY
     assert "STOP" in _PLANE_NAME_TO_KEY
-    assert "22" in _doc_text(), "число статусов в LITE_SETUP.md разъехалось с plane_sync"
+    assert "Оценка" in _PLANE_NAME_TO_KEY
+    assert "23" in _doc_text(), "число статусов в LITE_SETUP.md разъехалось с plane_sync"
 
 
 def test_env_map_and_smoke_are_linked_to_replication():

tests/test_orch020_estimator.py

@@ -0,0 +1,557 @@
+"""ORCH-020 / TC-01..TC-20: task-estimation side-mechanism (src/estimator.py +
+the «Оценка» Plane-status trigger).
+
+These exercise the DETERMINISTIC core (no network, no LLM, no live Plane/Telegram):
+  * the trigger wiring in handle_issue_updated -> handle_estimate (fail-closed, mutual
+    exclusion, anti-disruption, auto-return to Backlog, anti-loop, massivity);
+  * the pure forecast + story-point bucketiser (border cases, bootstrap, never-raise);
+  * the idempotent UPSERT ledger (task_estimates, keyed by work_item_id);
+  * the Plane writes (estimate_point for the forecast, point for the fact — not swapped,
+    fail-safe when the estimate-system is absent);
+  * the Telegram card line, the GET /queue block, the leaf kill-switch / scope.
+
+Контракт (ADR-001): the estimator is an OBSERVER/PRODUCER, never a Quality Gate / stage
+— STAGE_TRANSITIONS / QG_CHECKS / check_* / verdict-keys / existing schemas are NOT
+touched (TC-20). All Plane writes go through the ORCH-117 guard (the autouse
+``_plane_sandbox_only`` floor keeps the opt-in OFF -> a real write is impossible from a
+test process); we spy at the plane_sync boundary to assert the calls without network.
+"""
+import asyncio
+import os
+import tempfile
+
+os.environ.setdefault("ORCH_DB_PATH", os.path.join(tempfile.gettempdir(), "test_orch020_estimator.db"))
+os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token")
+os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token")
+
+import pytest  # noqa: E402
+
+import src.db as db  # noqa: E402
+from src import config as cfg  # noqa: E402
+from src import estimator  # noqa: E402
+
+_REPO = "orchestrator"
+_ORCH_PROJECT = "8da6aa25-a60e-44d6-a1e2-d8ae59aa7d6a"  # orchestrator Plane project id
+
+
+# ===========================================================================
+# Fixtures
+# ===========================================================================
+@pytest.fixture(autouse=True)
+def fresh_db(tmp_path, monkeypatch):
+    """Isolated tmp SQLite DB + estimator ON / empty scope (self-hosting) by default."""
+    dbfile = tmp_path / "est.db"
+    monkeypatch.setattr(db.settings, "db_path", str(dbfile))
+    monkeypatch.setattr(cfg.settings, "estimator_enabled", True, raising=False)
+    monkeypatch.setattr(cfg.settings, "estimator_repos", "", raising=False)
+    monkeypatch.setattr(cfg.settings, "estimator_min_samples", 3, raising=False)
+    monkeypatch.setattr(cfg.settings, "estimator_bootstrap_tokens", 2_000_000, raising=False)
+    monkeypatch.setattr(cfg.settings, "estimator_bootstrap_cost_usd", 3.0, raising=False)
+    monkeypatch.setattr(cfg.settings, "estimator_bootstrap_seconds", 1800, raising=False)
+    monkeypatch.setattr(cfg.settings, "estimator_sp_cost_thresholds", "0.50,2.00,5.00,12.00", raising=False)
+    monkeypatch.setattr(cfg.settings, "estimator_wall_cap_s", 86400, raising=False)
+    # reset in-process counters between tests
+    for k in estimator._COUNTERS:
+        estimator._COUNTERS[k] = 0
+    db.init_db()
+    yield
+
+
+@pytest.fixture
+def plane_spy(monkeypatch):
+    """Patch the plane_sync write boundary estimator uses, recording calls (no network)."""
+    calls = {"estimate_point": [], "point": [], "comment": [], "backlog": []}
+    monkeypatch.setattr(
+        "src.plane_sync.set_issue_estimate_point",
+        lambda wi, val, project_id=None: (calls["estimate_point"].append((wi, val)) or True),
+        raising=True,
+    )
+    monkeypatch.setattr(
+        "src.plane_sync.set_issue_point",
+        lambda wi, val, project_id=None: (calls["point"].append((wi, val)) or True),
+        raising=True,
+    )
+    monkeypatch.setattr(
+        "src.plane_sync.add_comment",
+        lambda wi, text, project_id=None, author=None: calls["comment"].append((wi, text)),
+        raising=True,
+    )
+    monkeypatch.setattr(
+        "src.plane_sync.set_issue_backlog",
+        lambda wi, project_id=None: calls["backlog"].append(wi),
+        raising=True,
+    )
+    return calls
+
+
+def _mk_task(plane_id, work_item_id, *, stage="created", track="full",
+             created_at="2026-06-17 10:00:00", updated_at="2026-06-17 10:30:00") -> int:
+    conn = db.get_db()
+    cur = conn.execute(
+        "INSERT INTO tasks (plane_id, work_item_id, repo, branch, stage, track, "
+        "created_at, updated_at) VALUES (?,?,?,?,?,?,?,?)",
+        (plane_id, work_item_id, _REPO, f"feature/{work_item_id}", stage, track,
+         created_at, updated_at),
+    )
+    conn.commit()
+    tid = int(cur.lastrowid)
+    conn.close()
+    return tid
+
+
+def _mk_run(task_id, *, cost=4.0, in_tok=1000, out_tok=500):
+    conn = db.get_db()
+    conn.execute(
+        "INSERT INTO agent_runs (task_id, agent, input_tokens, output_tokens, "
+        "cost_usd, started_at, finished_at) VALUES (?,?,?,?,?,?,?)",
+        (task_id, "developer", in_tok, out_tok, cost,
+         "2026-06-17 10:00:00", "2026-06-17 10:20:00"),
+    )
+    conn.commit()
+    conn.close()
+
+
+# ===========================================================================
+# TC-01 — trigger recognised (AC-T1)
+# ===========================================================================
+@pytest.mark.asyncio
+async def test_tc01_estimate_status_routes_to_handle_estimate(monkeypatch):
+    from src.webhooks import plane as plane_wh
+    from src.plane_sync import _PLANE_NAME_TO_KEY
+
+    assert _PLANE_NAME_TO_KEY.get("Оценка") == "estimate"
+
+    proj_states = {
+        "estimate": "EST-UUID", "stop": "STOP-UUID", "to_analyse": "TA-UUID",
+        "approved": "AP-UUID", "rejected": "RJ-UUID", "confirm_deploy": None,
+    }
+    monkeypatch.setattr("src.plane_sync.get_project_states", lambda pid: proj_states)
+    seen = []
+
+    async def _stub(data, project_id=""):
+        seen.append(data.get("id"))
+    monkeypatch.setattr(plane_wh, "handle_estimate", _stub)
+
+    await plane_wh.handle_issue_updated({"id": "PL-1", "state": {"id": "EST-UUID"}}, "proj")
+    assert seen == ["PL-1"]
+
+
+# ===========================================================================
+# TC-02 — fail-closed on a board without «Оценка» (AC-T5)
+# ===========================================================================
+@pytest.mark.asyncio
+async def test_tc02_failclosed_no_status(monkeypatch):
+    from src.webhooks import plane as plane_wh
+    from src.plane_sync import _DEFAULT_STATES
+
+    assert "estimate" not in _DEFAULT_STATES  # never force-filled -> .get -> None
+
+    proj_states = {
+        "stop": "STOP-UUID", "to_analyse": "TA-UUID", "approved": "AP-UUID",
+        "rejected": "RJ-UUID", "confirm_deploy": None,
+        # NOTE: no "estimate" key (board без статуса)
+    }
+    monkeypatch.setattr("src.plane_sync.get_project_states", lambda pid: proj_states)
+    seen = []
+
+    async def _stub(data, project_id=""):
+        seen.append(data.get("id"))
+    monkeypatch.setattr(plane_wh, "handle_estimate", _stub)
+
+    # An unrelated state -> the estimate branch is inert (no KeyError), no estimate.
+    await plane_wh.handle_issue_updated({"id": "PL-2", "state": {"id": "SOMETHING-ELSE"}}, "proj")
+    assert seen == []
+
+
+# ===========================================================================
+# TC-02b — the estimate gesture never aliases stop/approved/rejected
+# ===========================================================================
+@pytest.mark.asyncio
+async def test_tc02b_mutual_exclusion(monkeypatch):
+    from src.webhooks import plane as plane_wh
+
+    proj_states = {
+        "estimate": "EST-UUID", "stop": "STOP-UUID", "to_analyse": "TA-UUID",
+        "approved": "AP-UUID", "rejected": "RJ-UUID", "confirm_deploy": None,
+    }
+    monkeypatch.setattr("src.plane_sync.get_project_states", lambda pid: proj_states)
+    seen = {"estimate": [], "stop": []}
+
+    async def _est(data, project_id=""):
+        seen["estimate"].append(data.get("id"))
+
+    async def _stop(data, project_id=""):
+        seen["stop"].append(data.get("id"))
+    monkeypatch.setattr(plane_wh, "handle_estimate", _est)
+    monkeypatch.setattr(plane_wh, "handle_stop", _stop)
+
+    await plane_wh.handle_issue_updated({"id": "S", "state": {"id": "STOP-UUID"}}, "proj")
+    await plane_wh.handle_issue_updated({"id": "E", "state": {"id": "EST-UUID"}}, "proj")
+    assert seen["stop"] == ["S"]
+    assert seen["estimate"] == ["E"]
+
+
+# ===========================================================================
+# TC-03 — backlog estimate + auto-return to Backlog (AC-T1, AC-T2)
+# ===========================================================================
+@pytest.mark.asyncio
+async def test_tc03_backlog_estimate_and_return(monkeypatch, plane_spy):
+    from src.webhooks import plane as plane_wh
+
+    monkeypatch.setattr("src.plane_sync.fetch_issue_sequence_id", lambda iid, pid: 20)
+    await plane_wh.handle_estimate({"id": "PL-3"}, _ORCH_PROJECT)
+
+    row = db.get_estimate("ORCH-020")
+    assert row is not None
+    assert row["forecast_story_points"] in (1, 2, 3, 5, 8)
+    assert "ORCH-020" in plane_spy["backlog"]  # returned to Backlog
+
+
+# ===========================================================================
+# TC-04 — anti-disruption: active job -> no-op (AC-T6)
+# ===========================================================================
+@pytest.mark.asyncio
+async def test_tc04_anti_disruption_active_job(monkeypatch, plane_spy):
+    from src.webhooks import plane as plane_wh
+
+    tid = _mk_task("PL-4", "ORCH-044", stage="development")
+    db.enqueue_job("developer", _REPO, "x", task_id=tid)  # active (queued) job
+
+    called = []
+    monkeypatch.setattr(estimator, "estimate", lambda *a, **k: called.append(a))
+
+    await plane_wh.handle_estimate({"id": "PL-4"}, _ORCH_PROJECT)
+
+    assert called == []                       # estimate not run
+    assert db.get_estimate("ORCH-044") is None  # nothing written
+    assert plane_spy["backlog"] == []          # status not changed
+
+
+# ===========================================================================
+# TC-05 — anti-loop: Backlog matches no trigger branch (AC-T6)
+# ===========================================================================
+@pytest.mark.asyncio
+async def test_tc05_anti_loop_backlog_echo(monkeypatch):
+    from src.webhooks import plane as plane_wh
+
+    proj_states = {
+        "backlog": "BACKLOG-UUID", "estimate": "EST-UUID", "stop": "STOP-UUID",
+        "to_analyse": "TA-UUID", "approved": "AP-UUID", "rejected": "RJ-UUID",
+        "confirm_deploy": "CD-UUID",
+    }
+    # Backlog UUID must collide with NONE of the trigger branches (anti-loop invariant).
+    triggers = {proj_states[k] for k in
+                ("estimate", "stop", "to_analyse", "approved", "rejected", "confirm_deploy")}
+    assert proj_states["backlog"] not in triggers
+
+    monkeypatch.setattr("src.plane_sync.get_project_states", lambda pid: proj_states)
+    seen = []
+
+    async def _est(data, project_id=""):
+        seen.append(data.get("id"))
+    monkeypatch.setattr(plane_wh, "handle_estimate", _est)
+
+    # Inbound "state -> Backlog" echo: no trigger branch matches -> no estimate.
+    await plane_wh.handle_issue_updated({"id": "PL-5", "state": {"id": "BACKLOG-UUID"}}, "proj")
+    assert seen == []
+
+
+# ===========================================================================
+# TC-06 — massivity: N webhooks -> N estimates (AC-T3)
+# ===========================================================================
+@pytest.mark.asyncio
+async def test_tc06_massivity(monkeypatch, plane_spy):
+    from src.webhooks import plane as plane_wh
+
+    seqs = {"PL-A": 61, "PL-B": 62, "PL-C": 63}
+    monkeypatch.setattr("src.plane_sync.fetch_issue_sequence_id", lambda iid, pid: seqs[iid])
+
+    for pid in ("PL-A", "PL-B", "PL-C"):
+        await plane_wh.handle_estimate({"id": pid}, _ORCH_PROJECT)
+
+    for wi in ("ORCH-061", "ORCH-062", "ORCH-063"):
+        assert db.get_estimate(wi) is not None
+    assert len(plane_spy["backlog"]) == 3
+
+
+# ===========================================================================
+# TC-07 — idempotent re-estimation: UPSERT by work_item_id (AC-T4)
+# ===========================================================================
+def test_tc07_idempotent_upsert(plane_spy):
+    estimator.estimate("ORCH-070", None, _REPO, "status")
+    estimator.estimate("ORCH-070", None, _REPO, "status")  # re-estimate
+
+    conn = db.get_db()
+    n = conn.execute(
+        "SELECT COUNT(*) FROM task_estimates WHERE work_item_id = ?", ("ORCH-070",)
+    ).fetchone()[0]
+    conn.close()
+    assert n == 1  # single row, no duplicate
+
+    row = db.get_estimate("ORCH-070")
+    assert row["estimate_count"] == 2  # bumped on re-estimate
+    assert len(plane_spy["estimate_point"]) == 2  # estimate_point written each time
+
+
+# ===========================================================================
+# TC-08 — estimate() returns 4 values, SP in {1,2,3,5,8} (AC-1)
+# ===========================================================================
+def test_tc08_forecast_shape(plane_spy):
+    f = estimator.estimate("ORCH-080", None, _REPO, "status")
+    assert set(f) >= {"forecast_tokens", "forecast_seconds", "forecast_cost_usd", "story_points"}
+    assert f["story_points"] in (1, 2, 3, 5, 8)
+    assert isinstance(f["forecast_tokens"], int)
+    assert isinstance(f["forecast_cost_usd"], float)
+
+
+# ===========================================================================
+# TC-09 — story-point bucketiser: exact border semantics (AC-2)
+# ===========================================================================
+def test_tc09_story_points_borders():
+    sp = estimator.story_points_for
+    # thresholds 0.50, 2.00, 5.00, 12.00 ; <= ascending
+    assert sp(0.0) == 1
+    assert sp(0.50) == 1
+    assert sp(0.51) == 2
+    assert sp(2.00) == 2
+    assert sp(2.01) == 3
+    assert sp(5.00) == 3
+    assert sp(5.01) == 5
+    assert sp(12.00) == 5
+    assert sp(12.01) == 8
+    assert sp(1000.0) == 8
+    # accepts a forecast dict too
+    assert sp({"forecast_cost_usd": 0.4}) == 1
+    # every output is on-scale
+    for c in (0, 0.5, 1, 2, 3, 5, 8, 13, 50):
+        assert sp(c) in (1, 2, 3, 5, 8)
+
+
+# ===========================================================================
+# TC-10 — empty history -> bootstrap, never-raise on broken data (AC-1, AC-9)
+# ===========================================================================
+def test_tc10_bootstrap_and_never_raise(monkeypatch, plane_spy):
+    # empty history -> bootstrap (not an exception)
+    f = estimator._forecast(_REPO, "full")
+    assert f["forecast_cost_usd"] == 3.0
+    assert f["story_points"] == estimator.story_points_for(3.0)
+
+    # broken DB aggregate -> still bootstrap, no exception escapes
+    def _boom(repo, track):
+        raise RuntimeError("db down")
+    monkeypatch.setattr("src.db.completed_task_stats", _boom)
+    f2 = estimator._forecast(_REPO, "full")
+    assert f2["forecast_cost_usd"] == 3.0
+
+    # estimate() never-raise even if persistence fails
+    def _boom_rec(**kw):
+        raise RuntimeError("persist down")
+    monkeypatch.setattr("src.db.record_estimate", _boom_rec)
+    f3 = estimator.estimate("ORCH-100", None, _REPO, "status")
+    assert f3["story_points"] in (1, 2, 3, 5, 8)
+
+
+# ===========================================================================
+# TC-11 — fact on done from usage aggregates (AC-4)
+# ===========================================================================
+def test_tc11_fact_on_done(plane_spy):
+    tid = _mk_task("PL-11", "ORCH-110", stage="done")
+    _mk_run(tid, cost=4.0, in_tok=1000, out_tok=500)  # cost 4.0 -> SP 3
+
+    ok = estimator.record_actual_on_done(tid, _REPO, "ORCH-110")
+    assert ok is True
+
+    row = db.get_estimate("ORCH-110")
+    assert row["actual_story_points"] == 3
+    assert abs(row["actual_cost_usd"] - 4.0) < 1e-6
+    assert row["actual_tokens"] == 1500          # total_in (1000) + total_out (500)
+    assert row["actual_seconds"] == 1800          # 30-min wall
+    assert ("ORCH-110", 3) in plane_spy["point"]  # fact -> Plane `point`
+
+
+# ===========================================================================
+# TC-12 — forecast -> estimate_point, fact -> point; not swapped, no overwrite (AC-3/AC-4)
+# ===========================================================================
+def test_tc12_fields_not_swapped(plane_spy):
+    # forecast write -> estimate_point only
+    f = estimator.estimate("ORCH-120", None, _REPO, "status")
+    assert ("ORCH-120", f["story_points"]) in plane_spy["estimate_point"]
+    assert plane_spy["point"] == []  # forecast does NOT touch `point`
+
+    forecast_sp = db.get_estimate("ORCH-120")["forecast_story_points"]
+
+    # fact write -> point only, forecast untouched
+    tid = _mk_task("PL-12", "ORCH-120", stage="done")
+    _mk_run(tid, cost=0.2)  # cost 0.2 -> SP 1
+    estimator.record_actual_on_done(tid, _REPO, "ORCH-120")
+
+    assert ("ORCH-120", 1) in plane_spy["point"]
+    row = db.get_estimate("ORCH-120")
+    assert row["actual_story_points"] == 1
+    assert row["forecast_story_points"] == forecast_sp  # forecast NOT overwritten
+
+
+# ===========================================================================
+# TC-13 — «Оценка» line in the Telegram card; empty forecast -> omitted (AC-5)
+# ===========================================================================
+def test_tc13_card_line(plane_spy):
+    from src.notifications import render_task_tracker
+
+    # no forecast yet -> no line, card still renders
+    assert estimator.card_line("ORCH-130") is None
+    tid = _mk_task("PL-13", "ORCH-130", stage="development")
+    card_before = render_task_tracker(tid)
+    assert "Оценка" not in card_before
+
+    # after a forecast -> the line appears
+    estimator.estimate("ORCH-130", None, _REPO, "status")
+    line = estimator.card_line("ORCH-130")
+    assert line is not None and "Оценка" in line
+    card_after = render_task_tracker(tid)
+    assert "Оценка" in card_after
+
+
+# ===========================================================================
+# TC-14 — Plane comment with the forecast (AC-6)
+# ===========================================================================
+def test_tc14_comment_posted(plane_spy):
+    estimator.estimate("ORCH-140", None, _REPO, "status")
+    assert len(plane_spy["comment"]) == 1
+    wi, text = plane_spy["comment"][0]
+    assert wi == "ORCH-140"
+    assert "Оценка" in text
+
+
+# ===========================================================================
+# TC-15 — kill-switch off -> module inert (AC-9)
+# ===========================================================================
+@pytest.mark.asyncio
+async def test_tc15_kill_switch_off(monkeypatch, plane_spy):
+    from src.webhooks import plane as plane_wh
+    monkeypatch.setattr(cfg.settings, "estimator_enabled", False, raising=False)
+
+    assert estimator.applies(_REPO) is False
+
+    monkeypatch.setattr("src.plane_sync.fetch_issue_sequence_id", lambda iid, pid: 99)
+    await plane_wh.handle_estimate({"id": "PL-15"}, _ORCH_PROJECT)
+
+    assert db.get_estimate("ORCH-099") is None  # nothing written
+    assert plane_spy["backlog"] == []
+    assert plane_spy["estimate_point"] == []
+
+
+# ===========================================================================
+# TC-16 — scope: empty -> self-hosting only (AC-9)
+# ===========================================================================
+def test_tc16_scope(monkeypatch):
+    # empty scope -> self-hosting only
+    monkeypatch.setattr(cfg.settings, "estimator_repos", "", raising=False)
+    assert estimator.applies("orchestrator") is True
+    assert estimator.applies("enduro-trails") is False
+
+    # explicit CSV scope
+    monkeypatch.setattr(cfg.settings, "estimator_repos", "enduro-trails", raising=False)
+    assert estimator.applies("enduro-trails") is True
+    assert estimator.applies("orchestrator") is False
+
+
+# ===========================================================================
+# TC-17 — GET /queue has the estimator block (AC-9)
+# ===========================================================================
+def test_tc17_queue_block():
+    from src.main import queue
+    result = asyncio.run(queue())
+    assert "estimator" in result
+    block = result["estimator"]
+    assert block["enabled"] is True
+    assert "counters" in block
+    assert "ledger" in block
+
+
+# ===========================================================================
+# TC-18 — additive table + helpers; idempotent migration (AC-12)
+# ===========================================================================
+def test_tc18_table_and_helpers():
+    # CREATE TABLE IF NOT EXISTS is idempotent
+    db.init_db()
+    db.init_db()
+
+    # record (task_id nullable) -> get
+    rid = db.record_estimate(
+        "ORCH-180", repo=_REPO, task_id=None,
+        forecast_tokens=1000, forecast_seconds=600, forecast_cost_usd=1.5,
+        forecast_story_points=2, source="status",
+    )
+    assert rid > 0
+    row = db.get_estimate("ORCH-180")
+    assert row["task_id"] is None
+    assert row["forecast_story_points"] == 2
+    assert row["estimate_count"] == 1
+
+    # set_actual stores the fact + delta-computable; does not touch forecast
+    db.set_actual("ORCH-180", actual_tokens=2000, actual_seconds=900,
+                  actual_cost_usd=2.5, actual_story_points=3, task_id=42)
+    row = db.get_estimate("ORCH-180")
+    assert row["actual_story_points"] == 3
+    assert row["forecast_story_points"] == 2  # forecast preserved
+    assert row["task_id"] == 42               # linked later
+
+    # existing tables intact (additive only)
+    conn = db.get_db()
+    names = {r[0] for r in conn.execute(
+        "SELECT name FROM sqlite_master WHERE type='table'").fetchall()}
+    conn.close()
+    assert {"tasks", "agent_runs", "jobs", "task_estimates"} <= names
+
+
+# ===========================================================================
+# TC-19 — fail-safe Plane write when estimate-system absent (AC-12, NFR-7)
+# ===========================================================================
+def test_tc19_failsafe_plane_write(monkeypatch):
+    import src.plane_sync as ps
+    # estimate-system not configured -> resolve returns {} -> best-effort skip, no raise
+    monkeypatch.setattr(ps, "get_project_estimate_points", lambda pid: {})
+    assert ps.set_issue_estimate_point("ORCH-190", 3) is False  # skipped, never raises
+
+    # the forecast persists and the flow does not crash even with the estimate-system absent
+    monkeypatch.setattr(ps, "add_comment", lambda *a, **k: None)
+    f = estimator.estimate("ORCH-190", None, _REPO, "status")
+    assert f["story_points"] in (1, 2, 3, 5, 8)
+    assert db.get_estimate("ORCH-190") is not None
+
+
+# ===========================================================================
+# TC-20 — control-path anti-regression (AC-10, AC-11)
+# ===========================================================================
+def test_tc20_control_path_untouched():
+    from src.stages import STAGE_TRANSITIONS
+    from src.qg.checks import QG_CHECKS
+
+    # «Оценка» is NOT a pipeline stage / edge.
+    assert "estimate" not in STAGE_TRANSITIONS
+    for _stage, edges in STAGE_TRANSITIONS.items():
+        # no edge target (next stage / rollback / gate) is the estimate gesture:
+        # estimation never advances or routes a task through the stage machine.
+        string_targets = [v for v in edges.values() if isinstance(v, str)]
+        assert "estimate" not in string_targets, (
+            f"STAGE_TRANSITIONS[{_stage!r}] routes to the estimate gesture"
+        )
+
+    # No new QG check registered for estimation.
+    assert not any("estimate" in str(k).lower() for k in QG_CHECKS)
+
+    # The estimator leaf does not import stage_engine / launcher at module load
+    # (leaf invariant — never on the control path).
+    import sys
+    import importlib
+    importlib.reload(importlib.import_module("src.estimator"))
+    src_estimator = sys.modules["src.estimator"]
+    # the module references config + lazy imports only; assert it has no module-level
+    # binding to stage_engine / launcher
+    assert not hasattr(src_estimator, "stage_engine")
+    assert not hasattr(src_estimator, "launcher")
+
+    # Step 2 (adaptive model selection) is out of scope: no model/effort override here.
+    src_text = open(src_estimator.__file__, encoding="utf-8").read()
+    assert "resolve_agent_model" not in src_text
+    assert "resolve_agent_effort" not in src_text

tests/test_orch119_business_request.py

@@ -0,0 +1,263 @@
+"""ORCH-119: source-backed ``00-business-request.md`` (fix the hardcoded ``TBD``).
+
+The Description section of ``00-business-request.md`` must carry the ACTUAL Plane-issue
+``description`` instead of the historic hardcoded literal ``TBD``. Because the
+self-hosting ``orchestrator`` repo cuts its branch lazily at analyst-job claim (the
+deferred path B, ORCH-088), the description must be DURABLE-persisted on the ``tasks``
+row at creation time (mirror of ``tasks.title``) so it survives the gap between task
+creation and claim.
+
+These tests are network-free: the Gitea ``contents`` POST (httpx) and the deferred
+branch-cut coroutines are mocked; ``create_task_atomic`` runs against a real isolated
+SQLite DB. Mapping to ``04-test-plan.yaml``:
+
+  * TC-01 — MANDATORY regression: render contains the real description, not ``TBD``.
+  * TC-02 — fallback: empty/whitespace/None -> explicit safe marker, never raises.
+  * TC-03 — deferred path B: description persisted + rendered at materialisation.
+  * TC-04 — direct path A: ``_create_initial_docs`` writes the real description.
+  * TC-05 — schema backward-compat: ``_ensure_column`` is additive + idempotent.
+  * TC-06 — data integrity: multi-line markdown preserved; Gitea 422 -> no-op.
+  * TC-07 — anti-regression: gates / STAGE_TRANSITIONS / QG_CHECKS unchanged.
+"""
+
+import asyncio
+import base64
+import os
+import tempfile
+from types import SimpleNamespace
+
+import pytest
+
+_test_db = os.path.join(tempfile.gettempdir(), "test_orch119_business_request.db")
+os.environ["ORCH_DB_PATH"] = _test_db
+os.environ["ORCH_REPOS_DIR"] = tempfile.gettempdir()
+os.environ.setdefault("ORCH_GITEA_TOKEN", "test-token")
+os.environ.setdefault("ORCH_PLANE_API_TOKEN", "test-token")
+
+import src.db as _db  # noqa: E402
+from src.db import init_db, get_db, create_task_atomic  # noqa: E402
+from src.webhooks import plane  # noqa: E402
+
+
+@pytest.fixture(autouse=True)
+def fresh_db(monkeypatch):
+    monkeypatch.setattr(_db.settings, "db_path", _test_db)
+    if os.path.exists(_test_db):
+        os.unlink(_test_db)
+    init_db()
+    yield
+
+
+# ---------------------------------------------------------------------------
+# TC-01 (MANDATORY regression): the rendered body carries the real request
+#        text, NOT the historic hardcoded ``TBD``. Red before the fix
+#        (``_render_business_request`` did not exist / body was ``TBD``).
+# ---------------------------------------------------------------------------
+def test_tc01_render_contains_real_description():
+    desc = "Users need source-backed business requests captured from the Plane issue."
+    out = plane._render_business_request("ORCH-119", "Source-backed request", desc)
+
+    # The real request text reaches the artifact body...
+    assert desc in out
+    # ...the header / Work Item ID are still present (unchanged contract)...
+    assert "# Business Request: Source-backed request" in out
+    assert "Work Item ID: ORCH-119" in out
+    # ...and the Description body is NOT the bare ``TBD`` bug.
+    body = out.split("## Description", 1)[1]
+    assert "TBD" not in body
+
+
+# ---------------------------------------------------------------------------
+# TC-02 (fallback): empty / whitespace / None description -> explicit safe
+#        marker (never the bare ``TBD`` bug), and the renderer never raises.
+# ---------------------------------------------------------------------------
+@pytest.mark.parametrize("desc", ["", "   ", "\n\t  \n", None])
+def test_tc02_fallback_marker_no_raise(desc):
+    out = plane._render_business_request("ORCH-119", "Name", desc)
+    assert "описание отсутствует в источнике" in out
+    body = out.split("## Description", 1)[1]
+    assert "TBD" not in body
+
+
+# ---------------------------------------------------------------------------
+# TC-03 (deferred path B / self-hosting): description is persisted DURABLE on
+#        the tasks row at creation and rendered into the artifact when the
+#        deferred branch is materialised at claim (launcher).
+# ---------------------------------------------------------------------------
+def test_tc03_deferred_path_persists_and_renders(monkeypatch):
+    desc = "A durable source-backed description for the deferred path B (claim-time cut)."
+    row, created = create_task_atomic(
+        "plane-b", "ORCH-201", "orchestrator",
+        "feature/ORCH-201-x", "analysis", "Title B", desc,
+    )
+    assert created
+
+    # Durable: description survives in the tasks row (readable without the network).
+    got = get_db().execute(
+        "SELECT description FROM tasks WHERE id=?", (row["id"],)
+    ).fetchone()
+    assert got[0] == desc
+
+    captured = {}
+
+    async def _branch_spy(repo, branch):
+        captured["branch_cut"] = (repo, branch)
+
+    async def _docs_spy(repo, branch, work_item_id, name, description=None):
+        captured["description"] = description
+
+    # _materialize_deferred_branch imports these names from webhooks.plane at call
+    # time, so patching the source module attributes intercepts them.
+    monkeypatch.setattr(plane, "_create_gitea_branch", _branch_spy)
+    monkeypatch.setattr(plane, "_create_initial_docs", _docs_spy)
+
+    from src.agents.launcher import AgentLauncher
+    AgentLauncher()._materialize_deferred_branch(
+        "orchestrator", "feature/ORCH-201-x", "ORCH-201", "Title B", desc
+    )
+
+    assert captured.get("branch_cut") == ("orchestrator", "feature/ORCH-201-x")
+    assert captured.get("description") == desc
+
+
+# ---------------------------------------------------------------------------
+# TC-04 (direct path A / serial gate not applicable): _create_initial_docs
+#        writes the real description into the Gitea contents body.
+# ---------------------------------------------------------------------------
+def test_tc04_direct_path_renders_description(monkeypatch):
+    desc = "Direct path A description that must reach the artifact body verbatim."
+    captured = {}
+
+    class _Resp:
+        status_code = 201
+
+        def raise_for_status(self):
+            pass
+
+    class _Client:
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *a):
+            return False
+
+        async def post(self, url, json=None, headers=None, timeout=None):
+            captured["content"] = base64.b64decode(json["content"]).decode()
+            return _Resp()
+
+    monkeypatch.setattr(
+        plane, "httpx", SimpleNamespace(AsyncClient=lambda *a, **k: _Client())
+    )
+
+    asyncio.run(
+        plane._create_initial_docs("orchestrator", "feature/x", "ORCH-119", "Name", desc)
+    )
+
+    assert desc in captured["content"]
+    assert "## Description\n\nTBD\n" not in captured["content"]
+
+
+# ---------------------------------------------------------------------------
+# TC-05 (schema backward-compat): _ensure_column adds tasks.description on a
+#        pre-existing table without it; idempotent on re-run; creation works.
+# ---------------------------------------------------------------------------
+def test_tc05_schema_backward_compat(monkeypatch, tmp_path):
+    db_path = str(tmp_path / "bc.db")
+    monkeypatch.setattr(_db.settings, "db_path", db_path)
+
+    # Simulate an OLD tasks table WITHOUT the description column.
+    conn = _db.get_db()
+    conn.executescript(
+        """
+        CREATE TABLE tasks (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            plane_id TEXT, work_item_id TEXT, repo TEXT NOT NULL,
+            branch TEXT, stage TEXT DEFAULT 'created', plane_issue_id TEXT, title TEXT
+        );
+        """
+    )
+    conn.commit()
+    conn.close()
+
+    # init_db must add the column idempotently and never fail.
+    init_db()
+    cols = [r[1] for r in _db.get_db().execute("PRAGMA table_info(tasks)").fetchall()]
+    assert "description" in cols
+
+    init_db()  # re-run: _ensure_column is a no-op (idempotent)
+
+    # Task creation works and persists the description.
+    row, created = create_task_atomic(
+        "p1", "ORCH-1", "orchestrator", "b", "analysis", "T", "a real description"
+    )
+    assert created
+    got = get_db().execute(
+        "SELECT description FROM tasks WHERE id=?", (row["id"],)
+    ).fetchone()
+    assert got[0] == "a real description"
+
+
+# ---------------------------------------------------------------------------
+# TC-06 (data integrity): multi-line markdown with special chars is preserved
+#        verbatim (no truncation/escaping); Gitea 422 (file exists) -> no-op
+#        (single create attempt, body NOT overwritten).
+# ---------------------------------------------------------------------------
+def test_tc06_multiline_preserved_and_idempotent_422(monkeypatch):
+    desc = (
+        "# Heading\n\n- bullet with `inline code`\n"
+        "- second *italic* and __bold__\n\n"
+        "Paragraph with special chars: <>&\"' and a trailing word."
+    )
+    out = plane._render_business_request("ORCH-119", "N", desc)
+    assert desc in out  # preserved verbatim, no truncation/escaping
+
+    calls = []
+
+    class _Resp:
+        status_code = 422  # Gitea: file already exists
+
+        def raise_for_status(self):
+            raise AssertionError("422 must be a no-op, never raised")
+
+    class _Client:
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *a):
+            return False
+
+        async def post(self, url, json=None, headers=None, timeout=None):
+            calls.append(json)
+            return _Resp()
+
+    monkeypatch.setattr(
+        plane, "httpx", SimpleNamespace(AsyncClient=lambda *a, **k: _Client())
+    )
+
+    asyncio.run(
+        plane._create_initial_docs("orchestrator", "b", "ORCH-119", "N", desc)
+    )
+    # Exactly one create attempt; no follow-up PUT/overwrite of the existing body.
+    assert len(calls) == 1
+
+
+# ---------------------------------------------------------------------------
+# TC-07 (anti-regression): the pipeline machinery is untouched —
+#        00-business-request.md stays informational (not gate-parsed).
+# ---------------------------------------------------------------------------
+def test_tc07_gates_unchanged():
+    from src.stages import STAGE_TRANSITIONS
+    from src.qg.checks import QG_CHECKS
+
+    # Stage graph intact.
+    for st in ("created", "analysis", "architecture", "development",
+               "review", "testing", "deploy-staging", "deploy", "done"):
+        assert st in STAGE_TRANSITIONS
+
+    # The named checks still exist with their canonical names.
+    for chk in ("check_analysis_complete", "check_architecture_done",
+                "check_ci_green", "check_tests_passed"):
+        assert chk in QG_CHECKS
+
+    # 00-business-request.md is informational: no check is keyed on it.
+    assert not any("business" in k.lower() for k in QG_CHECKS)

tests/test_serial_gate_branch.py

@@ -68,7 +68,9 @@ async def _drive_start_pipeline(monkeypatch, gate_applies: bool):
     async def _branch_spy(repo, branch):
         branch_calls.append((repo, branch))
 
-    async def _docs_spy(repo, branch, wi, name):
+    # ORCH-119: _create_initial_docs gained an additive `description` arg; the spy
+    # accepts it so the serial-gate invariant assertions below stay 1:1.
+    async def _docs_spy(repo, branch, wi, name, description=None):
         docs_calls.append((repo, branch, wi, name))
 
     monkeypatch.setattr(plane, "_create_gitea_branch", _branch_spy)