Compare commits

..

1 Commits

Author SHA1 Message Date
post-deploy-monitor
295304b422 docs(ORCH-021): post-deploy HEALTHY/NONE for ORCH-126
All checks were successful
CI / test (push) Successful in 1m11s
2026-06-17 12:11:36 +03:00
92 changed files with 138 additions and 8367 deletions

View File

@@ -239,19 +239,6 @@ ORCH_SERIAL_GATE_ENABLED=true
ORCH_SERIAL_GATE_REPOS=
ORCH_SERIAL_GATE_FREEZE_ENABLED=true
ORCH_SERIAL_GATE_PAUSE_ENABLED=true
# ORCH-120 (adr-0053): analyst open-questions -> Needs Input. Activates the dead
# "analyst asks BLOCKING questions -> 01-questions.md -> Needs Input" path in
# _handle_analysis_approved_flow. Additive, never-raise, self-hosting scope;
# STAGE_TRANSITIONS / QG_CHECKS / check_* / machine-verdict / DB schema UNCHANGED.
# ANALYST_QUESTIONS_GATE_ENABLED=false -> _handle_analysis_approved_flow runs its
# ORIGINAL pre-ORCH-120 order (files_ok first, then flat isfile check) byte-for-byte.
# ANALYST_QUESTIONS_GATE_REPOS (CSV) -> scope; EMPTY = self-hosting only (orchestrator).
# ANALYST_NEEDS_INPUT_AUTOPAUSE_ENABLED=true (default) -> auto-park a Needs-Input task
# (db.set_task_paused) so the repo serial-gate FIFO does not wedge while we wait for a
# human; unpark on resume. false -> operator-park only (POST /serial-gate/pause).
ORCH_ANALYST_QUESTIONS_GATE_ENABLED=true
ORCH_ANALYST_QUESTIONS_GATE_REPOS=
ORCH_ANALYST_NEEDS_INPUT_AUTOPAUSE_ENABLED=true
# ORCH-090: STOP-status task cancellation (stop active agent + full progress reset)
# and the relaunch-hole close. A dedicated Plane "STOP" status (logical key `stop`,
# fail-closed: absent from _DEFAULT_STATES, so a board without the status -> no-op)
@@ -282,32 +269,6 @@ 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

View File

@@ -40,21 +40,6 @@ bug-report (симптом / шаги воспроизведения / лока
**сложным/архитектурным/визуальным** (нужен ADR или макет) — выпусти **полный** analysis-пакет и
помечай в bug-report `escalate: full-cycle` (эскалация в полный цикл, ADR-001 D5 ORCH-019); оператор
снимает багфикс-трек эндпоинтом `POST /bug-fast-track/escalate`.
**Блокирующие вопросы → Needs Input (ORCH-120, adr-0053).** Если бизнес-запрос **блокирующе**
неоднозначен и выпустить корректные 4 deliverables нельзя без ответа заказчика — **НЕ фабрикуй**
требования ради сдачи файлов. Вместо этого через **Write tool** запиши
`docs/work-items/<plane-id>/01-questions.md` (скелет — `docs/_templates/01-questions.md`) со списком
**конкретных** блокирующих вопросов (с вариантами и тем, что разблокирует анализ). Наличие активных
вопросов уводит задачу в **Needs Input** (движок `_handle_analysis_approved_flow` ставит статус +
комментирует вопросы в Plane) — **приоритетно** над «файлы готовы». Это сигнальный артефакт (гейтом
не парсится), пиши его ТОЛЬКО при реальных блокерах.
**Поведение на перезапуске (resume).** После ответа заказчика в Plane тебя перезапускают: прочитай
**свежие комментарии-ответы**, затем (а) если все блокеры сняты — выпусти **полный** валидный пакет
(4 файла); свежий пакет автоматически **supersedeит** старый `01-questions.md` по mtime (повторного
Needs Input не будет); (б) если часть вопросов осталась — **перепиши** `01-questions.md`, оставив
только актуальные блокеры (снова Needs Input). Не оставляй устаревшие вопросы вперемешку с новыми.
</task>
<deliverables>
@@ -67,10 +52,6 @@ Needs Input не будет); (б) если часть вопросов оста
| `03-acceptance-criteria.md` | Критерии приёмки (чёткие условия PASS/FAIL) |
| `04-test-plan.yaml` | План тестов (unit, integration; pytest) |
**When-applicable (сигнальный, ORCH-120):** `01-questions.md` — пишется **только** при блокирующих
открытых вопросах (см. `<task>`) **вместо** сфабрикованных 4 файлов; скелет —
`docs/_templates/01-questions.md`. Не machine-verdict, гейтом не парсится.
**Скелеты:** бери из `docs/_templates/` (одноимённые файлы) — не угадывай структуру.
**Эталон качества/полноты:** заполненные work item **ORCH-088** и **ORCH-073**
ориентируйся на их детальность и формат.

View File

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

View File

@@ -3,56 +3,6 @@
Формат: [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).
- **D2 — Чистый claim (FR-2/AC-3):** `claim_next_job` при флипе `queued→running` сбрасывает `pid=NULL, run_id=NULL` тем же существующим UPDATE (defense-in-depth поверх D1) → между claim и стампом `pid` в `_spawn` строка несёт `pid IS NULL`, не чужой pid. SELECT-гейт (`status='queued' AND available_at<=now` + dep/serial-gate) — **не тронут** (offline hot-path, NFR-2; без нового SELECT/сети).

View File

@@ -149,12 +149,6 @@ 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` |

View File

@@ -47,7 +47,6 @@ check_tests_passed → check_staging_status → check_deploy_status`.
|----------|----------------|-----------|------------------|--------------------------|-------------------------|
| `00-business-request.md` | система (Plane webhook `_create_initial_docs`) / заказчик | required | `created` (инициализация) | не гейтится (вход) | — |
| `01-brd.md` | analyst | required | `analysis` | exit-гейт `analysis→architecture` = `check_analysis_approved` (Approved + полнота файлов); helper `check_analysis_complete` (наличие `01/02/03/04`) | — |
| `01-questions.md` | analyst | when-applicable | `analysis` | **сигнальный** (гейтом НЕ парсится); механизм — ветка Needs Input в `_handle_analysis_approved_flow` (ORCH-120, adr-0053): активные блокирующие вопросы → `set_issue_needs_input` (приоритет над «файлы готовы») | — (не machine-verdict) |
| `02-trz.md` | analyst | required | `analysis` | то же | — |
| `03-acceptance-criteria.md` | analyst | required | `analysis` | то же | — |
| `04-test-plan.yaml` | analyst | required | `analysis` | то же | — |
@@ -73,10 +72,6 @@ check_tests_passed → check_staging_status → check_deploy_status`.
- **Категория `when-applicable`** = документ пишется при наличии соответствующего предмета
(инфра / данные / security / post-deploy). Его отсутствие — не нарушение приёмки.
- **`05-…` / `09-…` / `11-…`** — зарезервированные/legacy номера, в текущем каноне не используются.
- **Префикс `01-` (DQ-4 ORCH-120)** — общий для артефактов стадии `analysis` владельца `analyst`:
`01-brd.md` — обязательный deliverable (гейтится `check_analysis_complete`), `01-questions.md`
**сигнальный** when-applicable артефакт того же владельца/стадии. Коллизии нет: файлы разноимённые,
`check_analysis_complete` проверяет ровно `01-brd.md`/`02`/`03`/`04` (`01-questions.md` им не парсится).
---

View File

@@ -1,43 +0,0 @@
---
work_item: ORCH-NNN
stage: analysis
author_agent: analyst
status: needs-input
created_at: <YYYY-MM-DD>
model_used: <resolve ORCH-41>
---
# 01 — Открытые вопросы (Open Questions): ORCH-NNN — <название>
Work Item: **ORCH-NNN** · Repo: **<repo>** · Стадия: analysis
> **Сигнальный** when-applicable артефакт (ORCH-120, adr-0053). Пишется аналитиком через **Write
> tool** ТОЛЬКО при **блокирующей** неоднозначности бизнес-запроса, когда выпустить корректные 4
> deliverables нельзя без ответа заказчика. Наличие этого файла с **активными** вопросами уводит
> задачу в **Needs Input** (приоритет над «файлы готовы»). **Не** machine-verdict: гейтом
> (`check_analysis_complete`/`check_analysis_approved`) НЕ парсится — это сигнал движку
> (`_handle_analysis_approved_flow`).
>
> ⚠️ Если блокирующих вопросов НЕТ — **не создавай** этот файл; выпускай полный пакет (`01-brd.md`/
> `02-trz.md`/`03-acceptance-criteria.md`/`04-test-plan.yaml`). Не фабрикуй требования ради сдачи 4
> файлов.
## 1. Контекст
<Что именно в бизнес-запросе (`00-business-request.md`) блокирует выпуск корректного пакета. Какие
факты установлены, а какие — нет. На какой код `src/` это влияет.>
## 2. Блокирующие вопросы
> Каждый вопрос — конкретный, отвечаемый, с вариантами (где уместно) и указанием, почему ответ
> блокирует анализ. Нумеруй (Q-1, Q-2, …).
- **Q-1** — <вопрос>
- Вариант A: <…> (последствие)
- Вариант B: <…> (последствие)
- Почему блокирует: <без ответа нельзя выпустить BR/TRZ, т.к. …>
- **Q-2** — …
## 3. Что разблокирует анализ
<Какие ответы переводят задачу из Needs Input обратно в работу: после ответов заказчика в Plane
аналитик перезапускается (resume), читает свежие комментарии и выпускает полный пакет. Если часть
вопросов снята, а часть осталась — **перепиши** этот файл (оставь только актуальные блокеры), иначе
выпусти 4 deliverables (свежий пакет supersedeит этот файл по mtime, DQ-2).>

View File

@@ -25,7 +25,6 @@
- **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)
@@ -289,56 +288,6 @@ 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
```
@@ -701,35 +650,6 @@ ORCH-027 вводит детерминированный (без LLM) **гейт
`docs/work-items/ORCH-088/08-data-requirements.md`,
`docs/work-items/ORCH-124/06-adr/ADR-001-serial-gate-pause-without-blocking.md`.
### Открытые вопросы аналитика → Needs Input (ORCH-120 — реализовано, [adr-0053](adr/adr-0053-analyst-open-questions-needs-input-flow.md))
При неоднозначном бизнес-запросе у аналитика не было рабочего канала уточнения — он **фабриковал**
требования, чтобы сдать обязательные 4 файла. Механизм «вопросы → Needs Input» в
`_handle_analysis_approved_flow` (`src/stage_engine.py`) существовал, но был **мёртв** (контракт не в
промпте; ветка `files_ok` имела приоритет; Needs Input клинил serial-gate; нет гигиены устаревшего
`01-questions.md`). ORCH-120 **активирует и достраивает** путь — аддитивно, под kill-switch, скоуп
self-hosting, never-raise; `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict/схема БД —
**байт-в-байт не тронуты** (поток — pre-gate-ветка движка, **не** QG; `01-questions.md` — сигнальный
артефакт, **не** machine-verdict).
- **Контракт + канон.** `.openclaw/agents/analyst.md` документирует «блокирующие вопросы →
`01-questions.md`, НЕ фабриковать deliverables»; `01-questions.md` стандартизирован как
`when-applicable` сигнальный артефакт (скелет `docs/_templates/` + строка `PIPELINE_DOCS.md`).
- **Приоритет «вопросы активны» > «файлы готовы»** в `_handle_analysis_approved_flow` (DQ-3) →
блокирующие вопросы достигают Needs Input даже при частичных/сфабрикованных deliverables. Чистая
логика решения — leaf `src/analyst_questions.py` (`questions_gate_applies`/`autopause_applies`/
`questions_active`, never-raise); side-effects (`set_issue_needs_input`/коммент/Telegram/park) —
в `stage_engine` (`_decide_analysis_outcome`/`_emit_analysis_*`).
- **Авто-park (DQ-1)** через ось «пауза» ORCH-124 (`db.set_task_paused` при Needs Input) → задача
исключается из «активного» предиката serial-gate, FIFO репо не клинит, пока ждём человека;
**resume + unpark** в `handle_status_start` (analysis-ветка, `clear_task_paused`).
- **Устаревание (DQ-2)** — детерминированный offline freshness-supersede по mtime (вопросы активны,
пока пакет неполон ИЛИ `01-questions.md` не старше всех 4 deliverables) → полный свежий пакет
supersedeит старый файл без зависимости от LLM.
- **Флаги** (`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 только у аналитика) не расширяется.
Детали — `docs/work-items/ORCH-120/06-adr/ADR-001-analyst-open-questions-needs-input.md`.
### Авто-режим по лейблам: autoApprove + autoDeploy (ORCH-089 — реализовано)
Конвейер имеет два **человеческих** гейта, тормозящих пакетный автономный прогон (эпик
ORCH-088): гейт BRD (`analysis`: ждёт ручного `Approved`) и гейт прод-деплоя (`deploy`:
@@ -1524,7 +1444,6 @@ 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)
@@ -1535,7 +1454,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) + estimator (ORCH-020) + 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) + 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` |
@@ -1544,8 +1463,6 @@ 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) |

View File

@@ -1,82 +0,0 @@
---
work_item: ORCH-120
stage: architecture
author_agent: architect
status: proposed
created_at: 2026-06-17
model_used: claude-opus-4-8
---
# ADR-0053: Поток «открытые вопросы аналитика → Needs Input» (приоритет + пауза + resume)
Сквозной (cross-cutting) ADR. Детальное решение задачи —
`docs/work-items/ORCH-120/06-adr/ADR-001-analyst-open-questions-needs-input.md`.
Статус: **Proposed** · Дата: 2026-06-17 · Источник: **ORCH-120** (bug → escalate full-cycle)
## Контекст
Конвейер обязывает аналитика выпустить 4 файла (`01-brd`/`02-trz`/`03-acceptance-criteria`/
`04-test-plan.yaml`), иначе exit-гейт `analysis` не пройдёт. При неоднозначном бизнес-запросе
(классика — `Description: TBD`) у аналитика нет рабочего канала уточнения → он **фабрикует**
требования. Механизм «вопросы → Needs Input» в `_handle_analysis_approved_flow`
(`src/stage_engine.py`) **существует, но мёртв** из-за четырёх смежных дефектов: контракт не
доведён до промпта; ветка `files_ok` имеет приоритет над веткой вопросов; Needs Input клинит
serial-gate репо (ORCH-088); нет гигиены устаревшего `01-questions.md`.
Поток пересекает несколько подсистем, поэтому фиксируется сквозным ADR (анти-археология ORCH-078:
блок `_handle_analysis_approved_flow` несёт 3+ маркера — ORCH-066/088/089/124):
- **ORCH-066** — Needs Input принадлежит **только** аналитику (слой B индикации ≠ слой A стадий).
- **ORCH-088** — per-repo serial-gate: «активная задача» по `tasks.stage NOT IN ('done','cancelled')`.
- **ORCH-124** (adr-0051) — ортогональная ось «пауза» (`tasks.paused_at`): исключает задачу из
«активного» предиката, **не** обходя оси `task_deps`/`repo_freeze`/терминал.
- **ORCH-089** — autoApprove (человеческий BRD-гейт по лейблу) в той же ветке `files_ok`.
## Решение
**Активировать мёртвый путь четырьмя согласованными изменениями** — аддитивно, под kill-switch,
скоуп self-hosting, never-raise:
1. **Контракт промпта + канон артефакта.** `.openclaw/agents/analyst.md` документирует канал
«блокирующие вопросы → `01-questions.md`, НЕ фабриковать deliverables»; `01-questions.md`
стандартизирован как **сигнальный** when-applicable артефакт (скелет `docs/_templates/` +
строка манифеста `PIPELINE_DOCS.md`) — **не** machine-verdict (гейтом не парсится, BR-6).
2. **Приоритет «вопросы активны» > «файлы готовы».** В `_handle_analysis_approved_flow` предикат
активных вопросов проверяется **до** ветки `files_ok` → блокирующие вопросы надёжно достигают
Needs Input даже при частичных/сфабрикованных deliverables.
3. **Авто-park через ось «пауза» ORCH-124.** Переход в Needs Input вызывает `db.set_task_paused`
→ задача исключается из «активного» предиката serial-gate → следующая задача репо входит в
`analysis`, пока первая ждёт человека (не клинит FIFO неопределённо долго).
4. **Resume + unpark.** `handle_status_start` (analysis-resume) снимает паузу (`clear_task_paused`)
и перезапускает аналитика; relaunch-guard ORCH-090 (только `analysis`) не ослаблен.
**Устаревание `01-questions.md` (детерминированно, offline):** freshness-gated supersede по mtime —
вопросы «активны», пока пакет неполон ИЛИ `01-questions.md` не старше всех 4 deliverables; полный
свежий пакет supersedeит старый файл (выбор механизма и отвергнутые альтернативы — ADR-001 DQ-2).
## Инварианты (нормативно)
- **Поток — pre-gate-ветка движка, НЕ Quality Gate.** `STAGE_TRANSITIONS` / реестр и имена
`QG_CHECKS` / семантика `check_analysis_complete`/`check_analysis_approved` / machine-verdict-ключи
/ схемы существующих таблиц — **байт-в-байт не тронуты**.
- **Без схемы БД:** переиспользуется `tasks.paused_at` (ORCH-124); новых таблиц/колонок нет.
- **ORCH-066 не расширяется:** Needs Input остаётся **только** у аналитика.
- **ORCH-124 не регрессирует:** пауза ортогональна — оси `task_deps`/`repo_freeze`/терминал
`{done,cancelled}` `paused_at` **не читают**; анти-stale-base ORCH-088 цел (нормальная задача
`paused_at IS NULL` держит гейт; свежесть базы на resume — существующими механизмами).
- **Self-hosting-безопасность:** поток только меняет Plane-статус/паузу/коммент и читает worktree —
не деплоит, не рестартит прод-контейнер, не пушит в `main`, не трогает detached-процессы.
- **never-raise / обратимость:** все врезки изолированы и деградируют к прежнему поведению;
3 флага (`analyst_questions_gate_enabled` / `analyst_questions_gate_repos` /
`analyst_needs_input_autopause_enabled`) с безопасными дефолтами → off/out-of-scope = байт-в-байт
как до ORCH-120 (enduro не затронут).
## Последствия
Конвейер перестаёт строить решения поверх домыслов; serial-gate не клинит на задаче, ждущей
человека (поддержка автономного пакетного прогона ORCH-088); аналитик получает легитимный канал
уточнения. Цена — узкое связывание индикации с осью планировщика при авто-park (смягчено флагом +
узким триггером + never-raise) и зависимость supersede от mtime (смягчено: полный прогон всегда
пишет свежие deliverables + контракт промпта). Детали, альтернативы и риски —
`docs/work-items/ORCH-120/06-adr/ADR-001-analyst-open-questions-needs-input.md`,
`docs/work-items/ORCH-120/10-tech-risks.md`.

View File

@@ -1,94 +0,0 @@
---
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`.

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

@@ -8,7 +8,7 @@
| Роль | Стадия | Вход | Выходные артефакты | Machine-verdict ключ |
|------|--------|------|--------------------|----------------------|
| `analyst` | analysis | бизнес-запрос (`00-business-request.md`) | `01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`, `04-test-plan.yaml`; when-applicable сигнальный `01-questions.md` | — (гейт проверяет полноту пакета + одобрение человека) |
| `analyst` | analysis | бизнес-запрос (`00-business-request.md`) | `01-brd.md`, `02-trz.md`, `03-acceptance-criteria.md`, `04-test-plan.yaml` | — (гейт проверяет полноту пакета + одобрение человека) |
| `architect` | architecture | пакет аналитики | `06-adr/ADR-NNN-*.md`, when-applicable `07-infra-requirements.md` / `08-data-requirements.md`, `10-tech-risks.md` | — (гейт проверяет наличие ADR) |
| `developer` | development | ТЗ + ADR | код в `src/`, тесты в `tests/`, обновлённые доки, `CHANGELOG.md`, PR в Gitea | — (гейт — зелёный CI ветки) |
| `reviewer` | review | PR diff + ТЗ/ADR | `12-review.md` | `verdict:` (`APPROVED` \| `REQUEST_CHANGES`) |
@@ -18,15 +18,6 @@
Machine-verdict ключи читаются гейтами **только из YAML-frontmatter** артефакта (никогда из
прозы) и неизменны байт-в-байт — подробнее в [блоке качества](tech-quality-security.md).
> **Сигнальный канал аналитика → Needs Input (ORCH-120).** Если на стадии `analysis` аналитик
> упирается в блокирующие открытые вопросы, он не фабрикует обязательные deliverables, а выпускает
> when-applicable артефакт `01-questions.md` — задача уходит в **Needs Input** и (под флагом
> `analyst_needs_input_autopause_enabled`, скоуп self-hosting) автоматически встаёт на паузу, чтобы
> не клинить очередь репозитория, пока ждём ответа человека; ответ возобновляет анализ и снимает
> паузу. `01-questions.md` — сигнальный артефакт того же владельца/стадии, **не** machine-verdict и
> **не** один из 4 обязательных deliverables (exit-гейт `check_analysis_complete` его не парсит). Как
> это вплетено в serial-gate — [конвейер](tech-pipeline.md).
## Модель и эффорт
Модель и эффорт каждой роли резолвятся **только из конфига** (не из промпта); текущие

View File

@@ -49,7 +49,6 @@ 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
при старте): обновление платформы не требует ручных миграций.

View File

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

View File

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

View File

@@ -107,17 +107,12 @@ created → analysis → architecture → development → review → testing →
прода после выкладки замораживает репозиторий (freeze) до ручного разбора — следующие задачи
ждут.
У FIFO-порядка есть управляемое исключение — **пауза без блокировки**: более раннюю задачу можно
снять с активной очереди репозитория, не дожидаясь её завершения, и тогда срочный успешник её
обгоняет. Паузу (durable-сигнал `tasks.paused_at`) ставят два источника. **Оператор** — явно
(`POST /serial-gate/pause`, снять — `/resume`). **Движок** — автоматически, когда аналитик
упирается в блокирующие открытые вопросы и задача уходит в **Needs Input** (узкий триггер под
флагом `analyst_needs_input_autopause_enabled`, скоуп self-hosting); на возобновлении (ответ
человека) движок снимает паузу симметрично. Авто-park нужен, чтобы задача, ждущая человека часы
или дни, не клинила FIFO-очередь репозитория в автономном пакетном прогоне. Пауза — отдельная ось:
она ≠ отмена (задача не терминальна и возвращается в гейт обратной командой) и **не** обходит ни
freeze, ни объявленные зависимости. Свежесть базы возобновлённой задачи гарантируют те же
механизмы (отложенный срез ветки + ребейз на слиянии), что и для обычного FIFO.
У FIFO-порядка есть управляемое исключение — **пауза без блокировки**: оператор может явно
поставить более раннюю задачу на паузу (durable-сигнал `tasks.paused_at`), и тогда срочный
успешник её обгоняет, не дожидаясь завершения. Пауза — отдельная ось: она ≠ отмена (задача не
терминальна и возвращается в гейт обратной командой) и **не** обходит ни freeze, ни объявленные
зависимости. Свежесть базы возобновлённой задачи гарантируют те же механизмы (отложенный срез
ветки + ребейз на слиянии), что и для обычного FIFO.
## Отмена: STOP → `cancelled`
@@ -126,27 +121,12 @@ 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 (отмена) и «Оценка» (прогноз с возвратом в
Backlog, см. выше). Они инициируют действие или снимают ожидание человека, но саму машину стадий
не подменяют. Полная карта статусов — в [инженерном справочнике](../architecture/README.md).
но никогда не управляют конвейером (машина стадий — только `STAGE_TRANSITIONS`). Управляющих
статусов ровно три: запуск в работу, Approved/Confirm Deploy (человеческие гейты) и STOP
(отмена). Полная карта статусов — в [инженерном справочнике](../architecture/README.md).
---

View File

@@ -1,7 +0,0 @@
# 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, на проработку. Источник: голосовая постановка Славы + раскладка Стрим.

View File

@@ -1,238 +0,0 @@
---
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` (архитектор).

View File

@@ -1,132 +0,0 @@
---
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 / 1N) — гибче для калибровки, но требует решить пороги
отображения и маппинг диапазон→модель.
- Вариант 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 зафиксирую лишь требование-ограничение «стоимость оценки ≪
> ожидаемой экономии».

View File

@@ -1,166 +0,0 @@
---
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 пропуск, не падение.

View File

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

View File

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

View File

@@ -1,262 +0,0 @@
---
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`
(строки 163181) разбирает 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-карточка)

View File

@@ -1,76 +0,0 @@
---
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`).

View File

@@ -1,85 +0,0 @@
---
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`)
оставляет таблицу пустой/неиспользуемой — безвредно.

View File

@@ -1,47 +0,0 @@
---
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) — **низкий**; точность прогноза — итеративно улучшаемая
через заложенный леджер калибровки.

View File

@@ -1,106 +0,0 @@
---
verdict: APPROVED
work_item: ORCH-020
stage: review
author_agent: reviewer
status: approved
created_at: 2026-06-17
model_used: claude-opus-4-8
type: review
work_item_id: ORCH-020
version: 2
---
# Review ORCH-020 — Оценка задачи, запускаемая Plane-статусом «Оценка»
## Summary
Реализация **технически сильная и полная**: новый leaf `src/estimator.py` (never-raise, kill-switch
`estimator_enabled` + скоуп `estimator_repos`), детерминированная эвристика по истории завершённых
задач **без LLM** (как требует ADR-001 D1 и политика determinization ORCH-118), точечные аддитивные
врезки в `webhooks/plane.py` / `plane_sync.py` / `stage_engine.py` / `db.py` / `notifications.py` /
`main.py` / `config.py`. Все критерии приёмки (AC-T1…AC-T6, AC-1…AC-12) покрыты тестами
`tests/test_orch020_estimator.py` (TC-01…TC-20).
**Прогон тестов (зелёный):**
- `tests/test_orch020_estimator.py` + анти-дрейф доков (`test_system_docs`, `test_bundled_setup_doc`,
`test_lite_setup_doc`) — **92 passed**.
- Регрессы интеграционных точек (webhook/plane/config/stage/notif/db/queue/estimator) — **540 passed**.
**Соответствие ТЗ (ось 1) — полное.** FR-T1…FR-T10 реализованы: статус «Оценка» как fail-closed-триггер
(`_PLANE_NAME_TO_KEY["Оценка"]="estimate"`, отсутствует в `_DEFAULT_STATES`), `handle_estimate`
(guard-цепочка applies→анти-disruption), прогноз 4 величин + story-points `{1,2,3,5,8}`,
авто-возврат в Backlog (анти-loop), массовость (N вебхуков), идемпотентный UPSERT по `work_item_id`,
запись прогноза в `estimate_point` / факта в `point` (не перепутаны, факт не затирает прогноз),
Telegram-пункт + Plane-коммент, леджер `task_estimates`, опциональные `POST/GET /estimate`, read-only
блок `estimator` в `GET /queue`.
**Соответствие ADR (ось 2) — полное.** D1D12 реализованы дословно. Трассировка (ORCH-078): правки
маркированных блоков (`handle_issue_updated` — семейство STOP/Confirm Deploy; `_PLANE_NAME_TO_KEY`;
done-блок `stage_engine` с ORCH-114 lease/merge-lease-release) **аддитивны** и не ломают
зафиксированных инвариантов — ветка `estimate` стоит после `stop`, взаимоисключение жестов держится
различием UUID (проверено TC-02b), done-врезка идёт в своём `try/except` ПОСЛЕ решения о переходе.
**Качество кода (ось 3) — высокое.** never-raise-контракт выдержан во всех публичных функциях и
врезках; leaf не импортирует `stage_engine`/`launcher` на загрузке (TC-20). Сверено по коду:
колонки `agent_runs` (`input_tokens`/`output_tokens`/`cache_read_tokens`/`cache_creation_tokens`),
используемые `completed_task_stats`, существуют; `add_comment(..., author=)` — корректная сигнатура;
базис токенов прогноза (`completed_task_stats`) и факта (`task_usage_summary.total_in+total_out`)
**консистентен** (оба = input+cache_read+cache_creation+output) → дельта прогноз↔факт осмысленна.
**Документация (ось 4, приоритет) — обновлена в том же PR.** `src/` изменён И документация обновлена:
инженерный справочник, ADR (work-item + сквозной adr-0054), CHANGELOG, README (env-таблица), онбординг/
Lite/Bundled-доки + анти-дрейф тесты, **и бизнес-витрина `docs/overview/` (ORCH-011)** — устранён
блокер предыдущего ревью (run_id=800).
**Control-path не тронут (AC-10 подтверждён):** `git diff` не затрагивает `src/stages.py` и
`src/qg/checks.py`; `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict-ключи / схемы
существующих таблиц — байт-в-байт; `task_estimates` — единственный аддитивный объект
(`CREATE TABLE/INDEX IF NOT EXISTS`).
> **Контекст вердикта.** Предыдущее ревью (run_id=800) вынесло `REQUEST_CHANGES` c единственным P1 —
> витрина `docs/overview/` не отражала новую операторскую способность «Оценка». Блокер **устранён**
> коммитом `375bd46 docs(overview): отразить операторскую способность «Оценка» в витрине (ORCH-020)`;
> попутно ужесточена тавтологичная строка TC-20 (бывший P3). Оставшихся P0/P1 нет → `APPROVED`.
## Findings
### P0 — Blocker
- (нет)
### P1 — Must fix
- (нет — предыдущий P1 «витрина `docs/overview/` не обновлена» закрыт коммитом `375bd46`; см.
раздел «Документация»)
### P2 — Should fix
- (нет)
### P3 — Nice-to-have
- [ ] `src/plane_sync.py::_patch_issue_fields` — PATCH полей issue (`point`/`estimate_point`) проходит
guard ORCH-117 с меткой `plane_write_guard.OP_STATE`, хотя это не смена state. Функционально
безопасно (решение guard'а зависит от sandbox/prod-проекта, не от op-метки; op влияет лишь на
аудит-лог), но метка семантически неточна. Опционально — ввести/использовать op-константу для
field-PATCH ради точности аудит-лога. **Не блокирует.**
## Документация
**Обновлено в PR (корректно, golden source наравне с кодом):**
- `docs/architecture/README.md` — новый компонент «Task estimator», секция «Оценка задачи (ORCH-020)»,
таблица `task_estimates` в data-model, эндпоинты `POST/GET /estimate`, блок `estimator` в `GET /queue`,
статусная модель.
- ADR: `docs/work-items/ORCH-020/06-adr/ADR-001-task-estimation-status-trigger.md` + сквозной
`docs/architecture/adr/adr-0054-task-estimation-status-trigger.md`.
- `CHANGELOG.md` (`[Unreleased]`), `README.md` (env-таблица `ORCH_ESTIMATOR_*`, 9 ключей).
- `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`, не терминальная — корректно, иначе ложно сработал бы
терминал-детект ORCH-068).
- **Бизнес-витрина `docs/overview/` (ORCH-011) — обновлена в этом же PR (закрытие P1 прошлого ревью):**
`business.md` (способность «Оценка задачи до запуска» + сценарий 7), `presentation.md`
(исправлено «управляющих статусов ровно три» → жесты + оценка; добавлены жест и сценарий),
`tech-pipeline.md` (новая секция «Оценка задачи» + исправление статусной модели), `tech-integrations.md`
(исправлено «три управляющих статуса»), `tech-observability.md` (пункт «Оценка» в карточке + блок
`estimator` в `GET /queue`), `tech-data-model.md` (таблица `task_estimates`). Машинные факты витрины
(`tests/test_system_docs.py`) — зелёные.
**Требует обновления:** нет (документация полна и консистентна реализации).

View File

@@ -1,41 +0,0 @@
---
result: PASS
work_item: ORCH-020
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):
```
%]
........................................................................ [ 67%]
........................................................................ [ 70%]
........................................................................ [ 73%]
........................................................................ [ 76%]
........................................................................ [ 80%]
........................................................................ [ 83%]
........................................................................ [ 86%]
........................................................................ [ 89%]
........................................................................ [ 92%]
........................................................................ [ 96%]
........................................................................ [ 99%]
................ [100%]
=============================== warnings summary ===============================
src/config.py:8
/repos/_wt/orchestrator/feature_ORCH-020-/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
2248 passed, 1 warning in 116.06s (0:01:56)
```

View File

@@ -1,46 +0,0 @@
---
staging_status: SUCCESS
work_item: ORCH-020
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 df2396e6-fec8-403a-9fa5-9587d0c8465d (HTTP 204)
· CLEANUP DB: no task row found for plane_id=df2396e6-fec8-403a-9fa5-9587d0c8465d
· 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
```

View File

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

View File

@@ -1,181 +0,0 @@
---
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 задачи риски
минимальны).

View File

@@ -1,189 +0,0 @@
---
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).
```

View File

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

View File

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

View File

@@ -1,173 +0,0 @@
---
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`

View File

@@ -1,39 +0,0 @@
---
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` аналитиком осознанно не создан). Остаточный риск для прод-конвейера —
**пренебрежимо мал**.

View File

@@ -1,85 +0,0 @@
---
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 (111)** — полное. **Соответствие ADR** — все решения
D1D5 реализованы. **Качество** — тест содержателен, детерминирован, с 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'а по этой оси нет.

View File

@@ -1,40 +0,0 @@
---
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)
```

View File

@@ -1,12 +0,0 @@
---
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.

View File

@@ -1,46 +0,0 @@
---
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
```

View File

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

View File

@@ -1,151 +0,0 @@
---
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,
~539551) → зовёт `_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` (строки ~514538), который вызывает то же
`_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).

View File

@@ -1,86 +0,0 @@
---
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).

View File

@@ -1,109 +0,0 @@
---
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 | правило сопровождения |

View File

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

View File

@@ -1,162 +0,0 @@
---
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 `:540551`) и уже используется для analyst-job (`task_desc`, `:723725`). Данные есть —
в 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` **НЕ** режет ветку/доки (`:697717`); срез
релоцирован на claim analyst-job в `src/agents/launcher.py::_materialize_deferred_branch`
(`:514538`), который располагает только `title` из строки `tasks`
(`SELECT branch, work_item_id, title FROM tasks`, `:561`). **`description` в таблице `tasks` не
персистится** (базовый `CREATE TABLE tasks`, `src/db.py:3142`, его не содержит) → путь B физически
не имеет доступа к описанию на момент claim.
Предусловие истинности данных: QG-0 (`_qg0_errors`, `src/webhooks/plane.py:490500`) отклоняет
создание при `description` короче 20 символов ⇒ нормальный путь всегда имеет осмысленный текст; терять
его недопустимо.
Прямой прецедент: `tasks.title` — аддитивная колонка (`_ensure_column(conn,"tasks","title","TEXT")`,
`src/db.py:125`), записываемая атомарно при создании задачи (`create_task_atomic`, `src/db.py:678683`)
и читаемая в `_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:678683`), а не отдельным `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-м аргументом (`:514516`, `:582584`) и
передаёт в `_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

View File

@@ -1,49 +0,0 @@
---
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:3142`) **не трогается**.
- Индексы **не требуются** (колонка не участвует в выборках/JOIN; читается по PK `tasks.id`).
- `NULL` по умолчанию; для уже существующих задач остаётся `NULL` (ретро-генерация вне объёма).
## Новые/изменённые сущности
- **`tasks.description`** — plain-text описание запроса (предпочтительно `description_stripped`
Plane-issue), записывается **при создании задачи** внутри атомарного INSERT
`create_task_atomic` (`src/db.py:678683`; список колонок/значений расширяется, параметр
`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).

View File

@@ -1,37 +0,0 @@
---
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).

View File

@@ -1,151 +0,0 @@
---
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:560568`) **до** обоих 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`.

View File

@@ -1,40 +0,0 @@
---
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)
```

View File

@@ -1,12 +0,0 @@
---
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.

View File

@@ -1,46 +0,0 @@
---
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
```

View File

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

View File

@@ -1,7 +0,0 @@
# Business Request: BUG: analyst open questions must move task to Needs Input
Work Item ID: ORCH-120
## Description
TBD

View File

@@ -1,171 +0,0 @@
---
work_item: ORCH-120
stage: analysis
author_agent: analyst
status: ready-for-review
created_at: 2026-06-17
model_used: claude-opus-4-8
escalate: full-cycle
---
# 01 — BRD (бизнес-требования): ORCH-120 — Открытые вопросы аналитика должны переводить задачу в Needs Input
Work Item: **ORCH-120** · Repo: **orchestrator** · Стадия: analysis
> ⚠️ **Эскалация в полный цикл (`escalate: full-cycle`).** Это формально баг (метка `BUG:` в
> заголовке), но фикс требует архитектурных решений (правило приоритета веток в
> `_handle_analysis_approved_flow`, интеграция с осью «пауза» ORCH-124, семантика устаревания
> `01-questions.md`, стандартизация нового pipeline-артефакта) — нужен ADR. Поэтому выпущен
> **полный** analysis-пакет (01/02/03/04), а не облегчённый bug-shaped. Оператор снимает багфикс-трек
> командой `POST /bug-fast-track/escalate?work_item=ORCH-120`, после чего задача идёт через стадию
> `architecture` (ADR-001 D5 ORCH-019). Открытые проектные вопросы для архитектора — §6 (DQ-1…DQ-4).
## 1. Бизнес-контекст и проблема
При запуске конвейера аналитик (`analyst`) получает бизнес-запрос и **обязан** выпустить 4 файла
(`01-brd` / `02-trz` / `03-acceptance-criteria` / `04-test-plan.yaml`), иначе exit-гейт стадии
`analysis` не пройдёт. Если бизнес-запрос неоднозначен или неполон (классический пример — тело
запроса `Description: TBD`), у аналитика **нет рабочего канала** запросить уточнения у заказчика: он
вынужден **домысливать** требования и всё равно сдать 4 файла. Сфабрикованный пакет уходит в
`In Review` / `architecture` — то есть весь конвейер строит решение поверх выдуманных требований.
**Парадокс:** механизм «вопросы → Needs Input» в движке **уже есть, но мёртв**. Код
`src/stage_engine.py::_handle_analysis_approved_flow` (стр. 769786) читает файл
`docs/work-items/<wid>/01-questions.md` и при его наличии вызывает `set_issue_needs_input(...)` +
комментарий в Plane + Telegram. Однако:
1. **Контракт не доведён до аналитика.** Промпт `.openclaw/agents/analyst.md` **нигде** не упоминает
`01-questions.md`: ни в `<deliverables>`, ни в `<task>`. Скелета `docs/_templates/01-questions.md`
нет, в манифесте `docs/_standards/PIPELINE_DOCS.md` артефакт не описан. Аналитик физически не
знает, что у него есть канал «задать блокирующий вопрос», поэтому домысливает.
2. **Ошибка приоритета веток.** В `_handle_analysis_approved_flow` ветка `files_ok` (все 4 файла на
месте — `check_analysis_complete`) проверяется **первой** и делает `return` (стр. 711767). Ветка
`01-questions.md` (стр. 769) достижима, только если 4 файла НЕ полны. Значит, если аналитик сдал и
неполный/заглушечный пакет, и `01-questions.md` — движок уйдёт в `In Review`, проигнорировав
блокирующие вопросы. «Есть вопросы» должно иметь приоритет над «файлы на месте».
3. **Needs-Input блокирует serial-gate репо.** Задача в Needs Input остаётся в стадии `analysis`
(Plane-статус — слой B индикации, ORCH-066, **не** меняет `tasks.stage`) и при этом
`paused_at IS NULL`. По правилу serial-gate (ORCH-088) такая «активная» задача держит FIFO репо
закрытым: пока заказчик не ответит (часы/дни), ни одна следующая задача `orchestrator` не войдёт в
`analysis`. ORCH-124 ввёл ортогональную ось «пауза» (`tasks.paused_at` + `POST /serial-gate/pause|
resume`) ровно для случая «приостановлено, но не блокирует» — Needs-Input обязан её использовать.
4. **Нет гигиены устаревшего `01-questions.md`.** После ответа заказчика `handle_status_start`
перезапускает аналитика (`src/webhooks/plane.py:317381`). Если перезапущенный аналитик теперь
выпускает полный валидный пакет, старый `01-questions.md` остаётся в ветке. Без правила
«устаревания» он либо игнорируется (если `files_ok` побеждает), либо вечно перезапускает Needs
Input (если вопросы получат приоритет). Нужно явное правило supersede.
Корень — **разрыв контракта между промптом аналитика и движком** плюс **3 смежных дефекта потока**
(приоритет, блокировка очереди, устаревание). ORCH-120 закрывает их как единый «правильный поток
Needs Input».
**Связь с предшественниками (контекст резюма из бэклога):** задача разморожена после корневых
фиксов **ORCH-124** (ось «пауза без блокировки» — необходимый фундамент для требования BR-3) и
**ORCH-126** (queued-job не застревает со stale `run_id`/`pid` — гарантирует, что перезапущенный
после ответа аналитик-job реально заберётся из очереди). Оба — предусловия, а не объём ORCH-120.
## 2. Объём (scope)
### В объёме
- **Контракт промпта аналитика:** `.openclaw/agents/analyst.md` явно документирует канал
«блокирующие открытые вопросы → пиши `01-questions.md`, НЕ фабрикуй 4 deliverables», с форматом и
правилом поведения на перезапуске (прочитать ответы, снять устаревшие вопросы).
- **Канон артефакта:** скелет `docs/_templates/01-questions.md` + строка в манифесте
`docs/_standards/PIPELINE_DOCS.md` (артефакт-сигнал Needs Input; **не** machine-verdict-док, гейтом
не парсится).
- **Приоритет веток в движке:** в `_handle_analysis_approved_flow` блокирующие открытые вопросы
получают корректный приоритет → задача с вопросами надёжно достигает Needs Input.
- **Неблокирование serial-gate:** переход в Needs Input не держит FIFO репо закрытым неопределённо
долго (интеграция с осью «пауза» ORCH-124).
- **Гигиена устаревания:** перезапущенный аналитик, выпустивший полный валидный пакет без свежих
вопросов, приводит к `In Review`, а не к повторному Needs Input.
- **Корректность resume-петли:** ответ заказчика → перезапуск аналитика → снятие паузы (unpark), job
забирается из очереди.
- **Обязательный регресс-тест** (красный до фикса, зелёный после) + анти-дрейф структурные тесты.
### Вне объёма
- **Расширение владения Needs Input на других агентов.** ORCH-066 BR-10 фиксирует: Needs Input —
только у аналитика. Механизм не расширяется на architect/developer/reviewer/tester/deployer.
- **Новые QG-проверки и новые рёбра `STAGE_TRANSITIONS`.** Поток вопросов — pre-gate-ветка движка,
не Quality Gate. `check_analysis_complete`/`check_analysis_approved` — байт-в-байт.
- **Изменение семантики самого гейта `analysis`** (4 файла по-прежнему обязательны для прохождения
exit-гейта `analysis → architecture`).
- **Авто-ответ на вопросы / LLM-триаж ответов заказчика.** Ответы читает человек/аналитик, а не
отдельный автомат.
- **Машинерия багфикс-трека (ORCH-019)** и любые изменения вне аналитической стадии.
## 3. Заинтересованные стороны
- **Заказчик / оператор (Слава)** — получает осмысленный запрос уточнений вместо выдуманных
требований; отвечает в Plane и возвращает задачу в работу.
- **Конвейер `orchestrator` (self-hosting)** — перестаёт строить решения поверх домыслов; serial-gate
репо не клинит на задаче, ждущей человека.
- **Аналитик-агент** — получает легитимный канал «не знаю — спрошу» вместо принуждения к фабрикации.
- **Другие проекты на общем инстансе (enduro-trails)** — не затронуты (нулевая регрессия при
отсутствии `01-questions.md` и вне self-hosting-области).
## 4. Бизнес-требования (BR)
- **BR-1** — Аналитик, столкнувшийся с **блокирующей** неоднозначностью бизнес-запроса, ОБЯЗАН иметь
документированный канал запроса уточнений (`01-questions.md`) и НЕ должен фабриковать 4 deliverables
«лишь бы пройти гейт». Промпт `.openclaw/agents/analyst.md` описывает этот канал.
- **BR-2** — Наличие блокирующих открытых вопросов переводит задачу в Plane-статус **Needs Input** и
**останавливает** продвижение по конвейеру (не `In Review`, не `architecture`), даже если на диске
присутствуют частичные/заглушечные deliverables. Приоритет «вопросы» > «файлы на месте».
- **BR-3** — Задача в Needs Input **не блокирует** per-repo serial-gate FIFO неопределённо долго:
следующая задача `orchestrator` может войти в `analysis`, пока первая ждёт ответа человека.
- **BR-4** — После ответа заказчика (возврат issue в рабочий статус) аналитик перезапускается, читает
ответы и выпускает пакет. Если пакет полон и валиден и свежих блокирующих вопросов нет → задача
переходит в `In Review` (устаревший `01-questions.md` не должен повторно ронять её в Needs Input).
- **BR-5** — Поведение **обратимо и выборочно**: при отсутствии `01-questions.md` и выключенных
под-флагах поток Needs Input/паузы — байт-в-байт как до ORCH-120 (нулевая регрессия для enduro и
для штатной задачи без вопросов).
- **BR-6** — `01-questions.md` стандартизирован как pipeline-артефакт (скелет в `docs/_templates/` +
строка манифеста `PIPELINE_DOCS.md`): он сигнальный, **не** machine-verdict (гейтом не парсится).
## 5. Нефункциональные требования (NFR)
- **NFR-1 (never-raise / fail-safe)** — Любая ошибка новой логики (чтение файла, park-вызов,
определение приоритета) НЕ роняет `advance_stage`/launcher и деградирует к безопасному прежнему
поведению (как существующие leaf'ы `serial_gate`/`labels`/`cancel`).
- **NFR-2 (обратная совместимость)** — Стадии, кроме `analysis`, и Needs-Input-владение (ORCH-066) —
не трогаются. `STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict-ключи / семантика
exit-гейта `analysis` — байт-в-байт.
- **NFR-3 (инварианты serial-gate)** — Интеграция с паузой не регрессирует ORCH-088 (анти-stale-base:
отложенный срез ветки) и ORCH-124 (терминал `{done,cancelled}` и оси `task_deps`/`freeze`
не читают `paused_at`; пауза их не обходит).
- **NFR-4 (self-hosting-безопасность)** — Поток только меняет Plane-статус/паузу/комментарий и читает
worktree: не деплоит, не рестартит прод-контейнер, не пушит в `main`, не трогает detached-процессы.
- **NFR-5 (наблюдаемость)** — Переход в Needs Input и park/unpark логируются структурно; состояние
паузы видно в блоке `serial_gate` `GET /queue` (ORCH-124 уже отдаёт `paused`).
## 6. Допущения и ограничения
- **Допущение:** механизм чтения `01-questions.md` и `set_issue_needs_input` рабочие — задача в
основном **активирует и достраивает** существующий путь, а не строит его с нуля.
- **Допущение:** промпт `cat`-ается из worktree в момент запуска (ORCH-077 loading-model) → новый
контракт аналитика вступает в силу на следующем worktree от `main` без прод-рестарта.
- **Ограничение:** Plane-статус **Needs Input** должен существовать на доске проекта (ключ
`needs_input` уже в `plane_sync._DEFAULT_STATES`) — инфра-предусловие выполнено для ORCH.
- **Открытые проектные вопросы для архитектора (решить в `06-adr/`, НЕ в analysis):**
- **DQ-1** — Парковать задачу при Needs Input **автоматически** (`db.set_task_paused` в момент
перехода) или оставить park **операторским** (`POST /serial-gate/pause`)? Trade-off:
авто-park снимает риск стопора очереди (BR-3), но связывает индикацию (слой B) с осью планировщика.
- **DQ-2** — Механизм устаревания `01-questions.md` (BR-4): удалять файл при выпуске полного пакета /
приоритет по «вопросы свежее deliverables» (mtime/commit) / явный маркер «answered». Любой выбор
обязан быть детерминированным и не зависеть от сетевого Plane.
- **DQ-3** — Точное правило приоритета в `_handle_analysis_approved_flow`: проверять
`01-questions.md` ДО `files_ok`, либо ввести предикат «вопросы активны» с учётом DQ-2.
- **DQ-4** — Коллизия номера `01-questions.md` с `01-brd.md`. Движок читает именно `01-questions.md`
(`stage_engine.py:771`) — менять путь = код-изменение; стандарт документирует фактический путь.
- **Ограничение по флагам:** новое поведение (приоритет вопросов / авто-park) — под kill-switch с
безопасным дефолтом, чтобы откат был байт-в-байт (BR-5).
## 7. Критерии успеха
Аналитик при блокирующей неоднозначности пишет `01-questions.md`, задача надёжно переходит в Needs
Input, **не** блокирует serial-gate репо, после ответа заказчика возобновляется и выпускает корректный
пакет; при отсутствии вопросов — поведение прежнее. Детальные PASS/FAIL — `03-acceptance-criteria.md`.
## 8. Риски
- Связывание индикации (Plane-статус) с осью планировщика (пауза) при авто-park (DQ-1) — риск
непреднамеренного park; смягчение — kill-switch + явный лог.
- Устаревший `01-questions.md` зацикливает Needs Input (DQ-2) — смягчение детерминированным
supersede-правилом + регресс-тест BR-4.
- Регресс serial-gate (ORCH-088/124) при неаккуратной интеграции паузы — смягчение тестами NFR-3.
Детали и оценка — `10-tech-risks.md` (заполняет архитектор).

View File

@@ -1,111 +0,0 @@
---
work_item: ORCH-120
stage: analysis
author_agent: analyst
status: ready-for-review
created_at: 2026-06-17
model_used: claude-opus-4-8
---
# 02 — ТЗ (TRZ): ORCH-120 — Открытые вопросы аналитика → Needs Input
Work Item: **ORCH-120** · Repo: **orchestrator** · Стадия: analysis
> ТЗ описывает **конкретные изменения к реализации**, выведенные из BRD и фактического кода.
> Архитектурное обоснование (выбор механизма приоритета, авто-park vs operator-park, способ
> устаревания `01-questions.md`) — задача архитектора (`06-adr/`). Открытые проектные вопросы —
> BRD §6 (DQ-1…DQ-4).
## 1. Сводка изменения
Активировать и достроить уже существующий, но мёртвый путь «аналитик задаёт блокирующие вопросы →
задача в Needs Input». Четыре связанных изменения: (1) **контракт промпта** аналитика +
**канон артефакта** `01-questions.md`; (2) **приоритет** ветки вопросов над веткой «файлы готовы» в
`_handle_analysis_approved_flow`; (3) **неблокирование serial-gate** через ось «пауза» ORCH-124;
(4) **гигиена устаревания** `01-questions.md` на resume-петле. `STAGE_TRANSITIONS`, реестр `QG_CHECKS`,
семантика и имена `check_*`, machine-verdict-ключи, схема существующих таблиц — **не меняются**.
## 2. Задействованные модули / пути
| Путь | Действие |
|------|----------|
| `.openclaw/agents/analyst.md` | **изменить** — добавить контракт «блокирующие вопросы → `01-questions.md`, не фабриковать deliverables» (в `<task>` + `<deliverables>` + поведение на resume); сохранить канон 52d (5 секций, 6 полей frontmatter). |
| `docs/_templates/01-questions.md` | **создать** — скелет артефакта открытых вопросов (формат: контекст / список блокирующих вопросов с вариантами / что разблокирует анализ). |
| `docs/_standards/PIPELINE_DOCS.md` | **изменить** — строка манифеста §2 для `01-questions.md` (владелец `analyst`, категория `when-applicable`, стадия `analysis`, «механизм: ветка Needs Input в `_handle_analysis_approved_flow`», machine-key — «нет, сигнальный»). |
| `src/stage_engine.py` | **изменить**`_handle_analysis_approved_flow`: правило приоритета (вопросы активны → Needs Input до/вместо `files_ok`, см. DQ-3); опц. вызов park (DQ-1); гигиена устаревания (DQ-2). Всё never-raise. |
| `src/webhooks/plane.py` | **изменить (точечно)**`handle_status_start` (analysis-resume ветка, стр. 317381): при перезапуске аналитика снять паузу (`clear_task_paused`/`POST` эквивалент), чтобы re-enqueued job был claimable. |
| `src/db.py` | **переиспользовать**`set_task_paused` / `clear_task_paused` / `is_task_paused` (ORCH-124, уже есть; новых колонок НЕ вводить). |
| `src/serial_gate.py` | **не менять кодом** — ось «пауза» уже исключает `paused_at NOT NULL` (ORCH-124); ORCH-120 лишь корректно её триггерит. |
| `src/config.py` | **изменить** — добавить kill-switch(и) нового поведения (напр. `analyst_questions_gate_enabled`, опц. `analyst_needs_input_autopause_enabled`), env `ORCH_*`, безопасные дефолты. |
| `src/main.py` | **возможно** — наблюдаемость в блоке `GET /queue` (если потребуется доп. поле); pause/resume эндпоинты ORCH-124 переиспользуются как есть. |
> Точный набор правок в `src/**` финализирует архитектор (DQ-1…DQ-3). TRZ фиксирует **наблюдаемый
> контракт**, а не конкретную реализацию ветвления.
## 3. Функциональные требования
### FR-1 — Контракт промпта аналитика (BR-1, BR-6)
`.openclaw/agents/analyst.md` явно описывает: при **блокирующей** неоднозначности бизнес-запроса
аналитик пишет `docs/work-items/<plane-id>/01-questions.md` (через Write tool) со списком конкретных
блокирующих вопросов и **не** выпускает сфабрикованные 4 deliverables. Указывается поведение на
перезапуске: прочитать свежие комментарии-ответы в Plane, снять/не переписывать устаревшие вопросы,
выпустить полный пакет. Промпт остаётся в каноне 52d (5 секций, 6 полей schema, без `model:`).
### FR-2 — Приоритет «вопросы активны» (BR-2)
В `_handle_analysis_approved_flow` наличие **активных** блокирующих вопросов (`01-questions.md`,
с учётом supersede-правила DQ-2) ведёт к `set_issue_needs_input(...)` + комментарий + Telegram +
`result.note = "analysis-needs-input"` **независимо** от того, присутствуют ли на диске 4 файла.
Сейчас ветка `files_ok` (стр. 711) делает `return` до проверки вопросов (стр. 769) — порядок/предикат
исправляется так, что вопросы имеют приоритет. Happy-path (нет вопросов, 4 файла) → `In Review`
(`analysis-in-review`) без изменений.
### FR-3 — Неблокирование serial-gate (BR-3, NFR-3)
Переход в Needs Input приводит к тому, что задача **исключается** из «активного» предиката serial-gate
(ORCH-088), чтобы следующая задача `orchestrator` могла войти в `analysis`. Механизм — ось «пауза»
ORCH-124: `paused_at NOT NULL` уже исключается в `build_claim_clause`/`repo_has_active_task`/
`_per_repo_snapshot`. Авто-park vs operator-park — DQ-1. Терминал `{done,cancelled}` и оси
`task_deps`/`freeze` не читают `paused_at` — пауза их не обходит (инвариант ORCH-124 цел).
### FR-4 — Resume + unpark (BR-4)
`handle_status_start` (analysis-ветка) при перезапуске аналитика после ответа заказчика снимает паузу
(`clear_task_paused`), чтобы re-enqueued analyst-job был claimable (совместно с фиксом ORCH-126 о
stale `run_id`/`pid`). Существующий relaunch-guard ORCH-090 (relaunch только для `analysis`) — не
ослабляется.
### FR-5 — Гигиена устаревания `01-questions.md` (BR-4)
Перезапущенный аналитик, выпустивший полный валидный пакет (4 файла) **без свежих** блокирующих
вопросов, приводит к `In Review`, а не к повторному Needs Input. Реализация supersede — DQ-2
(детерминированно, offline, без сетевого Plane).
### FR-6 — Обратимость / kill-switch (BR-5)
Новое поведение под kill-switch с безопасным дефолтом: при отсутствии `01-questions.md` и выключенном
под-флаге поток Needs Input/паузы — **байт-в-байт** как до ORCH-120. Скоуп — self-hosting
(`orchestrator`); enduro не затронут.
## 4. Изменения API
**Нет новых эндпоинтов.** Переиспользуются существующие `POST /serial-gate/pause` и
`POST /serial-gate/resume` (ORCH-124, `src/main.py:396/442`) как операторский путь park/unpark (если
архитектор выберет operator-park, DQ-1). При авто-park вызывается `db.set_task_paused` напрямую из
движка. Блок `serial_gate` в `GET /queue` уже отдаёт `paused` — возможно дополнение полем-причиной.
## 5. Изменения схемы БД
**Нет.** Колонка `tasks.paused_at` уже введена ORCH-124 (`src/db.py:160`, `_ensure_column`). Новых
таблиц/колонок/индексов ORCH-120 не вводит.
## 6. Требования к новым/изменённым QG checks
**Нет.** `01-questions.md` — сигнальный артефакт, **не** machine-verdict-док; гейтом не парсится.
`check_analysis_complete` / `check_analysis_approved` / `_parse_*` — байт-в-байт. Поток вопросов
остаётся pre-gate-веткой движка (`_handle_analysis_approved_flow`), как и был.
## 7. Совместимость / регресс
- **Обратная совместимость:** при отсутствии `01-questions.md` ветвление `_handle_analysis_approved_flow`
и serial-gate работают как прежде (NFR-2). Стадии ≠ `analysis` — не трогаются.
- **Kill-switch:** новое поведение (приоритет вопросов / авто-park) выключаемо → откат байт-в-байт
(FR-6/BR-5). Область — self-hosting `orchestrator`.
- **Инварианты:** ORCH-066 (Needs Input только у аналитика) — не расширяется; ORCH-088/124 (анти-stale-base,
терминал/freeze/deps оси) — не регрессируют (NFR-3); never-raise (NFR-1); self-hosting-безопасность
(NFR-4: без прод-рестарта/`main`-push).
- **Полный регресс** `pytest tests/` остаётся зелёным; обязательный новый регресс-тест (TC-01) красный
до фикса и зелёный после.
- **Трассировка маркеров (ORCH-078):** правки в `_handle_analysis_approved_flow`/`serial_gate`/
`plane.py` сверяются с ADR ORCH-066 / ORCH-088 / ORCH-124 перед изменением (не сломать инварианты).

View File

@@ -1,142 +0,0 @@
---
work_item: ORCH-120
stage: analysis
author_agent: analyst
status: ready-for-review
created_at: 2026-06-17
model_used: claude-opus-4-8
---
# 03 — Критерии приёмки (Acceptance Criteria): ORCH-120 — Открытые вопросы аналитика → Needs Input
Work Item: **ORCH-120** · Repo: **orchestrator** · Стадия: analysis
Формат: каждый критерий имеет **PASS** (что должно быть истинно для приёмки) и **FAIL** (что
считается провалом). Reviewer проверяет их буквально по файлам репозитория и тестам.
---
## AC-1 — Приоритет вопросов над «файлы готовы» (регресс, обязательный)
**Условие:** `_handle_analysis_approved_flow` вызывается после аналитика, в worktree присутствуют
ОДНОВРЕМЕННО все 4 файла (`01-brd`/`02-trz`/`03-acceptance-criteria`/`04-test-plan.yaml`) И
`01-questions.md` с активными блокирующими вопросами.
- **PASS:** вызывается `set_issue_needs_input(work_item_id)`, `result.note == "analysis-needs-input"`,
`set_issue_in_review` НЕ вызывается, задача НЕ продвигается на `architecture`.
- **FAIL:** задача уходит в `In Review` / `architecture` (текущее ошибочное поведение — ветка
`files_ok` побеждает).
---
## AC-2 — Только вопросы, без deliverables (сохранение существующего поведения)
**Условие:** `01-questions.md` присутствует, 4 файла отсутствуют.
- **PASS:** `set_issue_needs_input` вызван, `result.note == "analysis-needs-input"`, текст вопросов
передан в Plane-комментарий и Telegram.
- **FAIL:** задача не переходит в Needs Input или падает с исключением.
---
## AC-3 — Happy-path без регресса
**Условие:** `01-questions.md` отсутствует, все 4 файла на месте.
- **PASS:** `set_issue_in_review` вызван, `result.note == "analysis-in-review"`, запрошен статус
`Approved` (поведение байт-в-байт как до ORCH-120, включая autoApprove-ветку ORCH-089).
- **FAIL:** задача ошибочно уходит в Needs Input либо happy-path-комментарий/статус изменился.
---
## AC-4 — Needs Input не блокирует serial-gate репо
**Условие:** задача A `orchestrator` в `analysis` переведена в Needs Input по `01-questions.md`;
существует более поздняя задача B того же репо.
- **PASS:** A исключена из «активного» предиката serial-gate (через `paused_at NOT NULL`, ось
ORCH-124); B может войти в `analysis` (claim analyst-job B не блокируется задачей A).
- **FAIL:** A продолжает держать FIFO репо закрытым (`repo_has_active_task` возвращает True из-за A),
B не может стартовать, пока заказчик не ответит.
---
## AC-5 — Resume снимает паузу и перезапускает аналитика
**Условие:** заказчик ответил и вернул issue в рабочий статус (In Progress / To Analyse) на стадии
`analysis`; активного job нет.
- **PASS:** `handle_status_start` снимает паузу (`paused_at` → NULL) и enqueue'ит analyst-job; job
забирается из очереди (не застревает со stale `run_id`/`pid`, ср. ORCH-126); relaunch-guard ORCH-090
(только `analysis`) соблюдён.
- **FAIL:** задача остаётся paused (job не claimable) ИЛИ перезапуск происходит на не-`analysis` стадии
(нарушение ORCH-090).
---
## AC-6 — Гигиена устаревшего `01-questions.md`
**Условие:** перезапущенный аналитик выпустил полный валидный пакет (4 файла) без свежих блокирующих
вопросов; устаревший `01-questions.md` от прошлого прогона мог остаться.
- **PASS:** задача переходит в `In Review` (`analysis-in-review`), а НЕ повторно в Needs Input;
supersede-правило (DQ-2) применено детерминированно и offline.
- **FAIL:** устаревший `01-questions.md` повторно роняет задачу в Needs Input (бесконечная петля).
---
## AC-7 — Контракт промпта аналитика (анти-дрейф)
**Условие:** содержимое `.openclaw/agents/analyst.md`.
- **PASS:** промпт документирует канал `01-questions.md` (блокирующие вопросы → Needs Input, не
фабриковать deliverables) И сохраняет канон 52d (5 XML-секций, 6 полей frontmatter-схемы, без
`model:`); `tests/test_agent_prompts_canon.py` зелёный, добавлен assert наличия контракта вопросов.
- **FAIL:** канал не документирован, либо нарушен канон 52d, либо тест канона красный.
---
## AC-8 — Канон артефакта `01-questions.md`
**Условие:** наличие скелета и записи в манифесте.
- **PASS:** `docs/_templates/01-questions.md` существует; `docs/_standards/PIPELINE_DOCS.md` содержит
строку манифеста для `01-questions.md` (владелец `analyst`, категория `when-applicable`, механизм
«ветка Needs Input», не machine-verdict).
- **FAIL:** скелет или строка манифеста отсутствуют.
---
## AC-9 — Обратимость / нулевая регрессия
**Условие:** kill-switch нового поведения выключен ИЛИ репо вне self-hosting-области (enduro-trails).
- **PASS:** ветвление `_handle_analysis_approved_flow` и serial-gate работают **байт-в-байт** как до
ORCH-120; `STAGE_TRANSITIONS`/`QG_CHECKS`/`check_*`/machine-verdict/схема БД не изменены.
- **FAIL:** обнаружено отличие поведения при выключенном флаге / для enduro.
---
## AC-10 — never-raise / self-hosting-безопасность
**Условие:** сбой новой логики (ошибка чтения файла, park-вызова, определения приоритета).
- **PASS:** `advance_stage`/launcher не падает, деградирует к безопасному прежнему поведению + WARNING;
поток не деплоит, не рестартит прод-контейнер, не пушит в `main`.
- **FAIL:** исключение всплывает наружу / встаёт конвейер / затронут прод/`main`.
---
## AC-11 — Полный регресс зелёный
**Условие:** `pytest tests/ -q`.
- **PASS:** вся сюита зелёная; новый обязательный регресс-тест (AC-1 / TC-01) красный на коде до фикса
и зелёный после.
- **FAIL:** любой тест красный, либо регресс-тест проходит и на дофиксовом коде (не доказывает баг).
---
## Сводная матрица AC ↔ FR/BR
| AC | Покрывает |
|----|-----------|
| AC-1 | BR-2 / FR-2 (регресс) |
| AC-2 | BR-2 / FR-2 |
| AC-3 | BR-5 / FR-2 |
| AC-4 | BR-3 / FR-3 |
| AC-5 | BR-4 / FR-4 |
| AC-6 | BR-4 / FR-5 |
| AC-7 | BR-1 / BR-6 / FR-1 |
| AC-8 | BR-6 / FR-1 |
| AC-9 | BR-5 / FR-6 / NFR-2 |
| AC-10 | NFR-1 / NFR-4 |
| AC-11 | NFR-2 |

View File

@@ -1,88 +0,0 @@
work_item: ORCH-120
stage: analysis
author_agent: analyst
status: ready-for-review
created_at: 2026-06-17
model_used: claude-opus-4-8
title: "Аналитик: открытые вопросы → Needs Input (приоритет, неблокирование serial-gate, resume)"
framework: pytest
scope: >
Покрывает поток «блокирующие открытые вопросы аналитика → Needs Input»:
приоритет ветки вопросов над «файлы готовы» (_handle_analysis_approved_flow),
неблокирование per-repo serial-gate (ось паузы ORCH-124), resume+unpark,
гигиена устаревшего 01-questions.md, контракт промпта и канон артефакта,
never-raise и нулевая регрессия. Вне покрытия: расширение Needs Input на
других агентов, новые QG/рёбра STAGE_TRANSITIONS, авто-ответ на вопросы.
notes: >
TC-01 — ОБЯЗАТЕЛЬНЫЙ регресс-тест: красный на коде ДО фикса (ветка files_ok
побеждает → In Review), зелёный ПОСЛЕ. Тесты движка прогоняют
_handle_analysis_approved_flow напрямую (launcher-путь), мокая plane_sync-
сеттеры и используя временный worktree (паттерн tests/test_analyst_status_only_regression.py
и tests/test_auto_approve_brd.py). Полный регресс pytest tests/ остаётся зелёным.
tests:
- id: TC-01
type: unit
description: "РЕГРЕСС: 4 файла + активный 01-questions.md одновременно -> set_issue_needs_input вызван, note=='analysis-needs-input', set_issue_in_review НЕ вызван (приоритет вопросов, AC-1). Красный до фикса."
module: tests/test_orch120_analyst_needs_input.py
expected: PASS
- id: TC-02
type: unit
description: "01-questions.md есть, 4 файлов нет -> Needs Input, текст вопросов в Plane-комментарии и Telegram (AC-2, сохранение существующего поведения)."
module: tests/test_orch120_analyst_needs_input.py
expected: PASS
- id: TC-03
type: unit
description: "Happy-path: нет 01-questions.md, 4 файла на месте -> set_issue_in_review, note=='analysis-in-review', запрос статуса Approved (AC-3, нет регресса)."
module: tests/test_orch120_analyst_needs_input.py
expected: PASS
- id: TC-04
type: integration
description: "Задача A в analysis переведена в Needs Input (paused_at NOT NULL) -> serial_gate исключает её из активного предиката; задача B того же репо может войти в analysis (AC-4, неблокирование FIFO)."
module: tests/test_orch120_serial_gate_needs_input.py
expected: PASS
- id: TC-05
type: integration
description: "Resume: возврат issue в рабочий статус на analysis при отсутствии активного job -> handle_status_start снимает паузу (paused_at->NULL) и enqueue'ит analyst-job; relaunch-guard ORCH-090 (только analysis) соблюдён (AC-5)."
module: tests/test_orch120_resume_unpark.py
expected: PASS
- id: TC-06
type: unit
description: "Гигиена устаревания: перезапущенный аналитик выпустил полный валидный пакет без свежих вопросов -> In Review, НЕ повторный Needs Input; supersede-правило детерминировано и offline (AC-6)."
module: tests/test_orch120_analyst_needs_input.py
expected: PASS
- id: TC-07
type: unit
description: "Анти-дрейф промпта: .openclaw/agents/analyst.md документирует канал 01-questions.md (блокирующие вопросы -> Needs Input, не фабриковать deliverables) и сохраняет канон 52d (5 секций, 6 полей, без model:) (AC-7)."
module: tests/test_agent_prompts_canon.py
expected: PASS
- id: TC-08
type: unit
description: "Канон артефакта: docs/_templates/01-questions.md существует и docs/_standards/PIPELINE_DOCS.md содержит строку манифеста для 01-questions.md (владелец analyst, when-applicable, не machine-verdict) (AC-8)."
module: tests/test_orch120_questions_artifact_canon.py
expected: PASS
- id: TC-09
type: unit
description: "never-raise: сбой новой логики (ошибка чтения 01-questions.md / park-вызова) не роняет advance_stage, деградирует к безопасному прежнему поведению + WARNING (AC-10)."
module: tests/test_orch120_analyst_needs_input.py
expected: PASS
- id: TC-10
type: unit
description: "Обратимость: kill-switch выключен ИЛИ репо вне self-hosting (enduro-trails) -> ветвление _handle_analysis_approved_flow и serial-gate байт-в-байт как до ORCH-120 (AC-9)."
module: tests/test_orch120_analyst_needs_input.py
expected: PASS
- id: TC-11
type: integration
description: "Полный регресс pytest tests/ зелёный; STAGE_TRANSITIONS/QG_CHECKS/check_* снапшот не изменён (AC-11, NFR-2)."
module: tests/test_stage_transitions_snapshot.py
expected: PASS

View File

@@ -1,248 +0,0 @@
---
work_item: ORCH-120
stage: architecture
author_agent: architect
status: proposed
created_at: 2026-06-17
model_used: claude-opus-4-8
---
# ADR-001: Открытые вопросы аналитика → Needs Input (приоритет, неблокирование serial-gate, resume)
Work Item: **ORCH-120** · Repo: **orchestrator** (self-hosting) · Стадия: architecture
Связь: BRD `01-brd.md`, ТЗ `02-trz.md`, AC `03-acceptance-criteria.md`, план тестов `04-test-plan.yaml`, риски `10-tech-risks.md`.
Сквозная регистрация: `docs/architecture/adr/adr-0053-analyst-open-questions-needs-input-flow.md`.
## Статус
Proposed
---
## Контекст
Задача — баг (`BUG:` в заголовке), **эскалированный в полный цикл** (`escalate: full-cycle`,
ADR-001 D5 ORCH-019): фикс требует архитектурных решений, поэтому выпущен полный analysis-пакет и
задача идёт через стадию `architecture`. Аналитик передал 4 открытых проектных вопроса (BRD §6:
DQ-1…DQ-4), которые и решаются этим ADR.
**Корень (верифицировано в коде).** Механизм «аналитик задаёт блокирующие вопросы → задача в
Needs Input» в движке **уже есть, но мёртв**: `src/stage_engine.py::_handle_analysis_approved_flow`
(ветка `01-questions.md`, стр. 769786) читает файл и вызывает `set_issue_needs_input(...)` +
коммент в Plane + Telegram. Четыре смежных дефекта делают его нерабочим:
1. **Контракт не доведён до аналитика.** `.openclaw/agents/analyst.md` нигде не упоминает
`01-questions.md` (ни в `<task>`, ни в `<deliverables>`); скелета `docs/_templates/01-questions.md`
нет; в `docs/_standards/PIPELINE_DOCS.md` артефакт не описан. Аналитик не знает о канале и
**домысливает** требования, чтобы сдать обязательные 4 файла.
2. **Ошибка приоритета веток.** Ветка `files_ok` (`check_analysis_complete` — все 4 файла на месте,
стр. 711767) проверяется **первой** и делает `return`; ветка `01-questions.md` (стр. 769)
достижима только если 4 файла НЕ полны. Сфабрикованный полный пакет уходит в `In Review`,
игнорируя блокирующие вопросы.
3. **Needs Input клинит serial-gate репо.** Задача в Needs Input остаётся в `stage='analysis'`
(Plane-статус — слой B индикации, ORCH-066, **не** меняет `tasks.stage`) и `paused_at IS NULL`.
По правилу ORCH-088 такая «активная» задача держит FIFO репо закрытым до ответа человека
(часы/дни) — ни одна следующая задача `orchestrator` не входит в `analysis`.
4. **Нет гигиены устаревшего `01-questions.md`.** После ответа заказчика `handle_status_start`
(`src/webhooks/plane.py:261`, analysis-resume) перезапускает аналитика; если тот выпускает
полный пакет, старый `01-questions.md` остаётся в ветке. Без правила supersede он либо
игнорируется, либо вечно роняет задачу в Needs Input.
**Что НЕ нужно строить с нуля** (BRD §6 «Допущение»): `set_issue_needs_input`, чтение файла,
ось «пауза» (`tasks.paused_at` + `db.set_task_paused`/`clear_task_paused`/`is_task_paused`,
ORCH-124), эндпоинты `POST /serial-gate/pause|resume`**уже существуют**. ORCH-120 **активирует
и достраивает** путь, а не изобретает его.
**Предусловия выполнены вне объёма:** ORCH-124 (ось «пауза без блокировки» — фундамент BR-3),
ORCH-126 (queued-job не застревает со stale `run_id`/`pid` — гарантирует claim перезапущенного
analyst-job). Plane-статус **Needs Input** существует (ключ `needs_input` в `_DEFAULT_STATES`).
---
## Решение (сводка)
Активировать мёртвый путь четырьмя согласованными изменениями, **аддитивно, под kill-switch,
скоуп self-hosting, never-raise**: (D1) контракт промпта + (D2) канон артефакта `01-questions.md`;
(D3) **приоритет** ветки вопросов над `files_ok` с детерминированным supersede; (D4) **авто-park**
при Needs Input через ось «пауза» ORCH-124; (D5) **resume + unpark** в `handle_status_start`.
`STAGE_TRANSITIONS` / реестр и имена `QG_CHECKS` / семантика `check_analysis_complete` /
`check_analysis_approved` / machine-verdict-ключи / схемы существующих таблиц — **байт-в-байт не
тронуты** (поток — pre-gate-ветка движка, **не** Quality Gate; артефакт — сигнальный, **не**
machine-verdict). Это решение DQ-1…DQ-4.
---
## Решения по открытым вопросам (DQ-1…DQ-4)
### DQ-1 — авто-park vs operator-park при Needs Input → **авто-park, config-gated**
**Решение.** В момент перехода в Needs Input движок вызывает `db.set_task_paused(task_id)`
**автоматически** (под под-флагом `analyst_needs_input_autopause_enabled`, скоуп self-hosting),
а на resume — `db.clear_task_paused(task_id)` (D5). Operator-park (`POST /serial-gate/pause`)
сохраняется как ручной fallback, но **не** обязателен для BR-3.
**Обоснование.** BR-3 и весь эпик ORCH-088 («1020 задач за ночь», автономный пакетный прогон)
требуют, чтобы Needs Input **не** клинил очередь. Operator-park вводит человеческий шаг в каждую
итерацию — это противоречит цели автономности: пока оператор не нажал pause, FIFO репо закрыт.
Авто-park снимает блокировку детерминированно и без человека.
**Снятие риска связывания индикации (слой B) с осью планировщика** (явный риск из BRD §6 DQ-1):
- Триггер узкий и детерминированный — **только** переход аналитика в Needs Input в
`_handle_analysis_approved_flow`, а не общее правило «статус → пауза».
- Отдельный под-флаг `analyst_needs_input_autopause_enabled` (независимый от questions-gate),
дефолт `True` в self-hosting-области → откат до operator-park одним флагом.
- never-raise: `set_task_paused` уже возвращает `False` на ошибке; сбой park **не** отменяет
переход в Needs Input (деградация к operator-park) и не роняет `advance_stage`.
- Симметричный unpark на resume (D5) исключает «застрявшую паузу».
**Инвариант ORCH-124 не нарушен:** `paused_at` исключает задачу только из оси «активная задача»
serial-gate; оси `task_deps`/`repo_freeze`/терминал `{done,cancelled}` `paused_at` **не читают**
пауза их не обходит (`src/serial_gate.py:33` нормативно).
### DQ-2 — устаревание `01-questions.md` (BR-4) → **freshness-gated supersede (mtime), детерминированно и offline**
**Решение.** Ввести чистый предикат `_questions_active(worktree_path, work_item_id, files_ok) -> bool`
в `stage_engine` (или leaf-хелпер), детерминированный и offline (только filesystem, без сети/git):
- `01-questions.md` отсутствует → **не активны** (`False`).
- Пакет **неполон** (`files_ok == False`) и файл присутствует → **активны** (`True`): вопросы есть,
deliverables нет — приоритет вопросов (AC-2).
- Пакет **полон** (`files_ok == True`) и файл присутствует → сверка свежести:
**superseded ⇔ все 4 deliverables строго новее `01-questions.md`** (по `os.path.getmtime`).
`superseded == True`**не активны** (`False`, → In Review, AC-6); иначе (вопросы не старше
новейшего deliverable) → **активны** (`True`, → Needs Input, AC-1).
**Почему mtime-freshness, а не альтернативы.** Кандидаты и причины отказа:
- **Удаление файла аналитиком** — у аналитика нет Delete-tool (только Write `docs/...`); полагаться
на «забыл удалить» нельзя; AC-6 явно допускает «файл **мог остаться** нетронутым».
- **Контент-маркер `status: resolved`** — требует, чтобы аналитик **переписал** файл; при
«файл остался нетронутым» (AC-6) маркера нет → ложный Needs Input. Плюс вводит парсинг
машинного ключа в сигнальный артефакт (трение с BR-6).
- **Git-recency коммитов** — надёжно в проде, но юнит-тесты (`04-test-plan.yaml`: временный worktree
с plain-файлами, паттерн `test_auto_approve_brd.py`) **не коммитят** → нетестируемо/хрупко.
- **mtime-freshness** — единственный механизм, который (а) тестируем на plain-файлах (тест задаёт
порядок записи/mtime), (б) offline и без нового парсинга, (в) **не зависит от действия LLM**:
на полном прогоне аналитик в любом случае пишет 4 deliverables (свежий mtime), поэтому
оставленный нетронутым старый `01-questions.md` автоматически superseded — ровно сценарий AC-6.
**Контракт промпта (D1) дополняет, не заменяет** механизм: на resume аналитик, у которого остались
блокеры, **перезаписывает** `01-questions.md` (свежий mtime → снова активен); при полном ответе —
просто пишет 4 deliverables, freshness supersedeит старые вопросы. Так оба слоя согласованы.
**Направление fail (never-raise, NFR-1) для DQ-2:**
- Ошибка `getmtime`/сверки при **доказанно существующем** `01-questions.md` → считать вопросы
**активными** (Needs Input) — безопасно для цели «не строить на домыслах».
- Катастрофический сбой (не можем определить даже наличие файла) → деградация к **прежнему**
поведению (`files_ok` → In Review) + WARNING.
### DQ-3 — точное правило приоритета в `_handle_analysis_approved_flow` → **вопросы проверяются ДО `files_ok`, под kill-switch**
**Решение.** Реструктурировать тело (только при `applies(repo)` и `analyst_questions_gate_enabled`):
```
files_ok, _ = QG_CHECKS["check_analysis_complete"](repo, work_item_id, branch)
questions_active = _questions_active(worktree, work_item_id, files_ok) # D2, never-raise
if questions_active:
set_issue_needs_input(work_item_id)
<Plane-коммент с текстом вопросов> + <Telegram> # как сейчас (стр. 770-784)
if analyst_needs_input_autopause_enabled and applies(repo):
db.set_task_paused(task_id) # D4 авто-park, never-raise
result.note = "analysis-needs-input"
return
if files_ok:
<ветка In Review + autoApprove ORCH-089> # существующая, байт-в-байт
return
<ветка "ни файлов, ни вопросов"> # существующая
```
- **Приоритет вопросов > «файлы на месте»** (AC-1): `questions_active` проверяется первым.
- **Happy-path** (нет файла вопросов): `questions_active == False` → ветка `files_ok` → In Review,
включая autoApprove ORCH-089 — **байт-в-байт** (AC-3).
- **Kill-switch / out-of-scope** (`analyst_questions_gate_enabled == False` ИЛИ репо вне области):
исполняется **исходный** порядок (`files_ok` первым; затем плоский `os.path.isfile(questions_path)`
— существующая ветка) — **байт-в-байт как до ORCH-120**, включая для enduro (AC-9).
### DQ-4 — коллизия номера `01-questions.md` с `01-brd.md` → **сохранить путь `01-questions.md`**
**Решение.** Движок уже читает именно `docs/work-items/<wid>/01-questions.md`
(`stage_engine.py:771`) — это **рабочий** контракт; смена пути = код-изменение + поломка читателя
без выгоды. Путь **сохраняется**. В `PIPELINE_DOCS.md` (D2) фиксируется нормативно: префикс `01-`
общий для артефактов стадии `analysis` аналитика; `01-brd.md` — обязательный deliverable,
`01-questions.md`**сигнальный** when-applicable артефакт того же владельца/стадии; коллизии нет,
т.к. файлы разноимённые, гейт `check_analysis_complete` проверяет ровно `01-brd.md`/`02`/`03`/`04`
(`01-questions.md` им не парсится).
---
## Изменения (карта, нормативно)
| Путь | Действие | Примечание |
|------|----------|------------|
| `.openclaw/agents/analyst.md` | изменить | D1: контракт «блокирующие вопросы → `01-questions.md`, НЕ фабриковать 4 deliverables» в `<task>`+`<deliverables>`+поведение на resume; **сохранить канон 52d** (5 секций, 6 полей, без `model:`). |
| `docs/_templates/01-questions.md` | создать | D2: скелет (контекст / список блокирующих вопросов с вариантами / «что разблокирует анализ»). |
| `docs/_standards/PIPELINE_DOCS.md` | изменить | D2: строка манифеста §2 (`01-questions.md`, владелец `analyst`, `when-applicable`, стадия `analysis`, механизм «ветка Needs Input в `_handle_analysis_approved_flow`», machine-key — «нет, сигнальный») + примечание о префиксе `01-` (DQ-4). |
| `src/stage_engine.py` | изменить | D3: приоритет + `_questions_active` (D2) + авто-park (D4); всё never-raise, под kill-switch. |
| `src/webhooks/plane.py` | изменить (точечно) | D5: analysis-resume ветка `handle_status_start` (стр. 317381) — `clear_task_paused(task_id)` (под autopause-флагом + `applies`), never-raise. |
| `src/config.py` | изменить | 3 новых ключа (ниже), безопасные дефолты. |
| `src/db.py` | переиспользовать | `set_task_paused`/`clear_task_paused` (ORCH-124) — **новых колонок нет**. |
| `src/serial_gate.py` | **не менять кодом** | ось «пауза» уже исключает `paused_at NOT NULL` (ORCH-124); ORCH-120 лишь корректно её триггерит (D4/D5). |
**Флаги (`src/config.py`), дефолты безопасны:**
| Ключ | Env | Дефолт | Назначение |
|------|-----|--------|------------|
| `analyst_questions_gate_enabled` | `ORCH_ANALYST_QUESTIONS_GATE_ENABLED` | `True` | kill-switch приоритета+supersede (D3). `False` → исходный порядок байт-в-байт. |
| `analyst_questions_gate_repos` | `ORCH_ANALYST_QUESTIONS_GATE_REPOS` | `""` | CSV; **пусто → self-hosting only** (`is_self_hosting_repo`, как ORCH-35/43/58). enduro не затронут. |
| `analyst_needs_input_autopause_enabled` | `ORCH_ANALYST_NEEDS_INPUT_AUTOPAUSE_ENABLED` | `True` | независимый под-тумблер авто-park/unpark (D4/D5). `False` → operator-park (`POST /serial-gate/pause`). |
`applies(repo)` (локально, без сети) проверяется **первым** — выключенный флаг / вне области
стоит ноль сетевых вызовов и даёт байт-в-байт прежнее ветвление (зеркало `serial_gate.applies`).
---
## Изменения схемы БД
**Нет.** Колонка `tasks.paused_at` введена ORCH-124 (`src/db.py:160`, `_ensure_column`). Новых
таблиц/колонок/индексов ORCH-120 не вводит. Поэтому отдельный `08-data-requirements.md` не выпускается.
## Инфраструктурные требования
**Нет нового.** Plane-статус **Needs Input** уже на доске (ключ `needs_input` в
`plane_sync._DEFAULT_STATES`); эндпоинты `POST /serial-gate/pause|resume` существуют (ORCH-124).
Поэтому отдельный `07-infra-requirements.md` не выпускается.
## QG / стадии
**Не тронуты.** `01-questions.md` — сигнальный, не machine-verdict (BR-6). `check_analysis_complete`/
`check_analysis_approved`/`_parse_*`/`STAGE_TRANSITIONS`/`QG_CHECKS` — байт-в-байт (NFR-2). Поток
вопросов остаётся pre-gate-веткой движка.
---
## Последствия
**Плюсы.**
- Аналитик получает легитимный канал «не знаю — спрошу» вместо принуждения к фабрикации (BR-1);
конвейер перестаёт строить решения поверх домыслов.
- Блокирующие вопросы надёжно достигают Needs Input даже при частичных deliverables (BR-2/AC-1).
- serial-gate репо не клинит на задаче, ждущей человека (BR-3/AC-4) — автономный пакетный прогон
(ORCH-088) не стопорится.
- Resume-петля корректна: ответ → unpark → claim перезапущенного analyst-job (BR-4/AC-5).
- Устаревший `01-questions.md` детерминированно supersedeится без зависимости от LLM (AC-6).
- Полная обратимость: 3 флага с безопасными дефолтами; вне области/выключено → байт-в-байт (AC-9).
**Минусы / ограничения.**
- Авто-park связывает индикацию (слой B) с осью планировщика — смягчено узким триггером,
отдельным флагом, never-raise и симметричным unpark (DQ-1).
- mtime-freshness теоретически хрупок при экзотической re-материализации worktree — на практике
устойчив (полный прогон всегда пишет свежие deliverables); смягчён fail-в-сторону-Needs-Input и
контрактом промпта (DQ-2, см. `10-tech-risks.md` TR-2).
- Needs Input по-прежнему **только** у аналитика (ORCH-066 BR-10 не расширяется) — намеренно.
**Трассировка маркеров (ORCH-078).** Правки в `_handle_analysis_approved_flow`/`handle_status_start`
сверены с ADR ORCH-066 (Needs-Input владение), ORCH-088/124 (serial-gate/пауза), ORCH-089
(autoApprove), ORCH-090 (relaunch-guard) — инварианты не сломаны. Блок `_handle_analysis_approved_flow`
несёт 3+ маркера → эволюция агрегирована в сквозном `adr-0053`.
## Соответствие AC
AC-1 → D3 (приоритет) + D2 (active при files_ok). AC-2 → D3 (questions при !files_ok). AC-3 → D3
(happy-path байт-в-байт). AC-4 → D4 (авто-park → `paused_at` исключает из активного предиката).
AC-5 → D5 (resume unpark). AC-6 → D2 (freshness supersede). AC-7 → D1 (контракт промпта). AC-8 → D2
(скелет + манифест). AC-9 → флаги/скоуп (байт-в-байт off/enduro). AC-10 → never-raise во всех врезках.
AC-11 → снапшот `STAGE_TRANSITIONS`/`QG_CHECKS` не изменён.

View File

@@ -1,41 +0,0 @@
---
work_item: ORCH-120
stage: architecture
author_agent: architect
status: proposed
created_at: 2026-06-17
model_used: claude-opus-4-8
---
# 10 — Технические риски: ORCH-120 — Открытые вопросы аналитика → Needs Input
Work Item: **ORCH-120** · Repo: **orchestrator** (self-hosting) · Стадия: architecture
> Информационный (гейтом не парсится). Перечисляет риски реализации и их митигейшн.
## Реестр рисков
| ID | Риск | Вер. | Влия. | Митигейшн |
|----|------|------|-------|-----------|
| TR-1 | **Связывание индикации (слой B) с осью планировщика** при авто-park (DQ-1): непреднамеренный park из-за широкого/ошибочного триггера. | Низ. | Сред. | Триггер узкий — **только** переход аналитика в Needs Input в `_handle_analysis_approved_flow`, не общее «статус→пауза». Отдельный под-флаг `analyst_needs_input_autopause_enabled` (откат к operator-park). never-raise: сбой `set_task_paused` не отменяет Needs Input. Симметричный unpark на resume (D5) исключает «застрявшую паузу». |
| TR-2 | **Хрупкость mtime-freshness** (DQ-2): re-материализация worktree выставляет близкие mtime → ложный supersede (AC-1 ломается) или ложная активность (AC-6 ломается). | Низ. | Сред. | Полный прогон аналитика **всегда** пишет 4 deliverables свежим mtime → старый нетронутый `01-questions.md` детерминированно старше (AC-6 устойчив). Сверка строгая (`>` для всех 4). Контракт промпта (D1): на resume с блокерами аналитик **перезаписывает** вопросы → свежий mtime (AC-1 устойчив). Fail-в-сторону-Needs-Input при ошибке `getmtime` на существующем файле. Покрыто TC-01/TC-06. |
| TR-3 | **Регресс serial-gate** (ORCH-088/124): неаккуратная интеграция паузы обходит freeze/deps или ломает анти-stale-base. | Низ. | Выс. | `serial_gate.py`/`task_deps.py`/`stages.py` **кодом не трогаются** — пауза уже ортогональна (ORCH-124: `paused_at` не читают оси freeze/deps/терминал). Анти-stale-base цел: нормальная задача `paused_at IS NULL` держит гейт; на resume свежесть базы дают существующие механизмы (отложенный срез / `auto_rebase_onto_main`). Снапшот-тест serial-gate + TC-04. |
| TR-4 | **Бесконечная петля Needs Input** при устаревшем `01-questions.md` (если supersede не сработал). | Низ. | Сред. | Детерминированный freshness supersede (DQ-2) + обязательный регресс TC-06 (полный пакет без свежих вопросов → In Review, не повторный Needs Input). Контракт промпта подкрепляет. |
| TR-5 | **Застрявшая пауза на resume** (task остаётся `paused_at NOT NULL` после ответа → семантика «активна, но помечена paused»). | Низ. | Низ. | D5: `clear_task_paused` на analysis-resume ветке `handle_status_start` (под autopause-флагом + `applies`), идемпотентно/never-raise. Ручной fallback — `POST /serial-gate/resume`. Покрыто TC-05. |
| TR-6 | **Нарушение never-raise** новой логики (чтение файла/park/приоритет) роняет `advance_stage`/launcher → встаёт конвейер всех проектов (self-hosting). | Низ. | Выс. | Все врезки в `try/except` с деградацией к **прежнему** поведению + WARNING (паттерн `serial_gate`/`labels`/`cancel`). `set_task_paused`/`clear_task_paused` уже never-raise (→ `False`). Покрыто TC-09. |
| TR-7 | **Регресс enduro / нулевой-флаг** (поведение отличается при выключенном kill-switch или вне self-hosting). | Низ. | Сред. | `applies(repo)` первым; off/out-of-scope → исходный порядок (`files_ok` первым + плоский isfile) **байт-в-байт**. enduro-аналитик `01-questions.md` не эмитит. Покрыто TC-10 + снапшот TC-11. |
| TR-8 | **Дрейф промпта** (контракт вопросов не задокументирован или сломан канон 52d). | Низ. | Низ. | Анти-дрейф `tests/test_agent_prompts_canon.py` (5 секций, 6 полей, без `model:`) + новый assert наличия контракта вопросов (TC-07); канон артефакта — TC-08. |
## Сводный вывод
Доминирующий класс — **корректность интеграции с serial-gate (ORCH-088/124) и never-raise на
self-hosting горячем пути** (TR-3/TR-6: высокое влияние, низкая вероятность). Оба полностью
структурно нейтрализованы: serial-gate кодом не трогается (пауза уже ортогональна), все врезки
изолированы и деградируют к прежнему поведению. Остальные риски — низкого влияния и покрыты
обязательными регресс-тестами (TC-01/TC-04/TC-05/TC-06/TC-09/TC-10).
Остаточный риск для прод-конвейера (self-hosting) — **низкий**: изменение аддитивно, под тремя
флагами с безопасными дефолтами (байт-в-байт откат), не деплоит / не рестартит прод / не пушит в
`main` / не трогает detached-процессы (NFR-4). Эскалация `arch:major-change` **не требуется**
(нет новой стадии/QG/компонента/смены БД); возврат в анализ **не требуется** (ТЗ удовлетворимо без
нарушения принципов архитектуры).

View File

@@ -1,105 +0,0 @@
---
verdict: APPROVED # APPROVED | REQUEST_CHANGES — строго одно из двух, UPPERCASE
work_item: ORCH-120
stage: review
author_agent: reviewer
status: approved
created_at: 2026-06-17
model_used: claude-opus-4-8
type: review
work_item_id: ORCH-120
version: 2
---
# Review ORCH-120 — Открытые вопросы аналитика → Needs Input
## Summary
Реализация **сильная, завершённая и корректная**. Ранее **мёртвый** путь «аналитик задаёт
блокирующие вопросы → `01-questions.md` → Needs Input» активирован четырьмя согласованными
изменениями (контракт промпта + канон артефакта; приоритет вопросов над `files_ok`; авто-park через
ось «пауза» ORCH-124; resume + unpark). Чистая логика вынесена в leaf `src/analyst_questions.py`
(never-raise, kill-switch, self-hosting-скоуп — зеркало `coverage_gate`/`serial_gate`); side-effects
изолированы в `stage_engine` (`_decide_analysis_outcome` / `_emit_analysis_needs_input` /
`_emit_analysis_in_review` / `_emit_analysis_empty`). ORCH-089 autoApprove-блок перенесён
**байт-в-байт** (сверено по `git show origin/main`). `STAGE_TRANSITIONS` / реестр и имена `QG_CHECKS`
/ `check_*` / machine-verdict-ключи / схема БД — **подтверждённо не тронуты** (пустой `git diff` по
`src/stages.py`, `src/qg/checks.py`, `src/db.py`). Все 11 AC реализованы и покрыты; обязательный
регресс-тест TC-01 (Bug-трек, ORCH-019 BR-4) — валидный фиксатор дефекта (красный на дофиксовом
`files_ok`-first порядке, зелёный после). Полный регресс `pytest tests/`**2205 passed** (86s).
**Блокировавший ранее дефект устранён.** Предыдущая ревизия (v1, run_id=780) выносила
`REQUEST_CHANGES` из-за единственного P1 — необновлённой **витрины системы** `docs/overview/`
(ось ORCH-011 / ORCH-079). Коммит `19c3177` обновил витрину в этом же PR (см. раздел «Документация»);
ось закрыта, `tests/test_system_docs.py` зелёный. Новых P0/P1/P2 нет → **APPROVED**.
## Findings
### P0 — Blocker
*(нет)*
### P1 — Must fix
*(нет)*
### P2 — Should fix
*(нет)*
### P3 — Nice to have
- [ ] Косметика (не привязано к правилу, не блокирует): `_decide_analysis_outcome` в gate-off ветке
повторно собирает путь `01-questions.md` (`os.path.join` + `os.path.isfile`), который уже
инкапсулирован в `analyst_questions.questions_active`; а `_emit_analysis_*` повторно резолвят
`get_worktree_path`. Дублирование намеренно (gate-off ветка = «оригинальный байт-в-байт порядок»),
поведенчески безвредно — при будущем рефакторе можно консолидировать резолв worktree.
## Документация
**Обновлено (проверено по diff) — golden source синхронизирован с кодом:**
- `docs/overview/tech-pipeline.md` — абзац «пауза без блокировки» теперь называет **два** источника
паузы (оператор `POST /serial-gate/pause` + **движок** авто-park на Needs Input, под флагом
`analyst_needs_input_autopause_enabled`, скоуп self-hosting; симметричный unpark на resume).
- `docs/overview/tech-observability.md` — пункт `GET /queue` обновлён: пауза/возобновление в serial
gate — от оператора **и** от движка (авто-park на Needs Input).
- `docs/overview/tech-agents.md` — строка `analyst` дополнена when-applicable сигнальным
`01-questions.md` + врезка о канале «блокирующие вопросы → Needs Input».
- `docs/architecture/README.md` — новый раздел «Открытые вопросы аналитика → Needs Input (ORCH-120 —
реализовано)» со ссылкой на adr-0053.
- `CHANGELOG.md` — запись `[Unreleased]` с полным описанием 4 изменений, флагов и витрины.
- `docs/_standards/PIPELINE_DOCS.md` — строка манифеста для `01-questions.md` (владелец `analyst`,
`when-applicable`, сигнальный, не machine-verdict) + примечание о префиксе `01-` (DQ-4).
- `.openclaw/agents/analyst.md` — контракт «блокирующие вопросы → `01-questions.md`, НЕ фабриковать
deliverables» + поведение на resume; канон 52d сохранён (анти-дрейф-assert
`test_orch120_analyst_documents_questions_channel` + канон-тесты зелёные).
- `docs/_templates/01-questions.md` — новый скелет (frontmatter 52c с плейсхолдерами; контекст /
блокирующие вопросы / что разблокирует анализ).
- `.env.example` — 3 ключа `ORCH_ANALYST_*` с описанием и безопасными дефолтами.
- 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`.
**Обзорные доки / витрина (ORCH-011 / ORCH-079):** `README.md` «Известные ограничения» проверен —
**нет** пункта, который закрывается этой задачей (мёртвый путь вопросов не значился ограничением),
обновление не требуется. Витрина `docs/overview/` обновлена в том же PR (см. выше). Ось закрыта.
**Нужно обновить:** ничего.
## Проверки осей (для прозрачности)
- **Соответствие ТЗ/AC:** AC-1…AC-11 реализованы и покрыты
(`tests/test_orch120_analyst_needs_input.py` TC-01…TC-10, `..._serial_gate_needs_input.py` TC-04
интеграционно через реальный `claim_next_job`, `..._resume_unpark.py` TC-05 + autopause-off,
`..._questions_artifact_canon.py`, assert канона). Полный регресс **2205 passed**. TC-01 — валидный
обязательный фиксатор (RED→GREEN), требование ORCH-019 BR-4 для Bug→escalate full-cycle выполнено.
- **Соответствие ADR / трассировка (ORCH-078):** реализация = ADR-001 / adr-0053 (D1…D5, DQ-1…DQ-4).
`STAGE_TRANSITIONS` / `QG_CHECKS` / `check_*` / machine-verdict / схема БД — байт-в-байт (пустой
diff). ОRCH-089 autoApprove перенесён вербатим; ось «пауза» ORCH-124 переиспользована (новых
колонок нет); инварианты ORCH-066 (Needs Input только у аналитика — не расширен), ORCH-088/124
(serial-gate/пауза — лишь корректно триггерится, код не тронут), ORCH-090 (relaunch-guard — unpark
врезан ПОСЛЕ гейта, под `current_stage=='analysis'`, не ослаблен) — сверены, не сломаны.
- **Качество кода:** leaf-паттерн чистый (импорт только `os`/`logging`/`config` + ленивый
`qg.checks`), never-raise во всех публичных функциях и врезках, kill-switch + скоуп корректны
(`questions_gate_applies`/`autopause_applies`), docstrings на публичных функциях содержательны.
Freshness-supersede (DQ-2) детерминирован и offline; fail-направление к Needs Input — безопасно
(«не строить на домыслах»). Гейт-off ветка восстанавливает оригинальный порядок байт-в-байт (AC-9).
- **Документация:** golden source (номерные/стандартные доки, ADR, CHANGELOG, `.env.example`) **и**
обзорная витрина `docs/overview/` обновлены в том же PR. Ось обзорных доков закрыта.
</content>
</invoke>

View File

@@ -1,40 +0,0 @@
---
result: PASS
work_item: ORCH-120
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%]
........................................................................ [ 75%]
........................................................................ [ 78%]
........................................................................ [ 81%]
........................................................................ [ 84%]
........................................................................ [ 88%]
........................................................................ [ 91%]
........................................................................ [ 94%]
........................................................................ [ 97%]
............................................. [100%]
=============================== warnings summary ===============================
src/config.py:8
/repos/_wt/orchestrator/feature_ORCH-120-bug-analyst-open-questions-mus/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
2205 passed, 1 warning in 102.38s (0:01:42)
```

View File

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

View File

@@ -1,46 +0,0 @@
---
staging_status: SUCCESS
work_item: ORCH-120
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 5db228da-d4be-4001-8233-e1579c6a7074 (HTTP 204)
· CLEANUP DB: no task row found for plane_id=5db228da-d4be-4001-8233-e1579c6a7074
· 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
```

View File

@@ -0,0 +1,14 @@
---
post_deploy_status: HEALTHY
action_taken: NONE
work_item: ORCH-126
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.

View File

@@ -82,10 +82,6 @@ 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",
@@ -938,7 +934,7 @@ def run_verify(
report.add("verify.registry", "запись реестра ORCH_PROJECTS_JSON", OK,
f"prefix={entry.work_item_prefix}, repo={entry.repo}")
# 2. Статусы: все 23 канонических имени (включая fail-closed Confirm Deploy/STOP/Оценка).
# 2. Статусы: все 22 канонических имени (включая fail-closed Confirm Deploy/STOP).
if observed.project is None or observed.states is None:
report.add("verify.plane.states", "статусы Plane-проекта", GAP,
"проект/статусы не читаются через API")

View File

@@ -512,8 +512,7 @@ class AgentLauncher:
return None
def _materialize_deferred_branch(
self, repo: str, branch: str, work_item_id: str | None, title: str | None,
description: str | None = None,
self, repo: str, branch: str, work_item_id: str | None, title: str | None
) -> None:
"""ORCH-088 (ADR-001 D1): create the deferred Gitea branch + initial docs.
@@ -525,12 +524,6 @@ 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
@@ -542,9 +535,7 @@ class AgentLauncher:
)
asyncio.run(_create_gitea_branch(repo, branch))
if work_item_id:
asyncio.run(
_create_initial_docs(repo, branch, work_item_id, name, description)
)
asyncio.run(_create_initial_docs(repo, branch, work_item_id, name))
def _spawn(self, agent: str, repo: str, task_content: str = None,
task_id: int = None, job_id: int = None) -> int:
@@ -565,14 +556,9 @@ 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, description FROM tasks WHERE id=?",
(task_id,),
"SELECT branch, work_item_id, title FROM tasks WHERE id=?", (task_id,)
).fetchone()
if task_id else None
)
@@ -594,7 +580,7 @@ class AgentLauncher:
_applies = False
if _applies:
self._materialize_deferred_branch(
repo, agent_branch, _br_row[1], _br_row[2], _br_row[3]
repo, agent_branch, _br_row[1], _br_row[2]
)
# ORCH-41: resolve the Plane project uuid for this repo so per-project

View File

@@ -1,169 +0,0 @@
"""ORCH-120 (adr-0053): analyst open-questions -> Needs Input — pure leaf helpers.
Activates and completes the dead "analyst asks BLOCKING questions ->
``01-questions.md`` -> Needs Input" path in
``stage_engine._handle_analysis_approved_flow``. This module holds ONLY the pure,
unit-testable decision logic; the side effects (set_issue_needs_input / Plane
comment / Telegram / auto-park) stay in ``stage_engine``.
Leaf pattern (mirror of ``coverage_gate`` / ``serial_gate`` / ``labels``): imports
only ``os`` / ``logging`` / ``config`` and lazily ``qg.checks.is_self_hosting_repo``;
NEVER imports ``stage_engine`` / ``launcher`` / ``db``.
What it decides (ADR-001 D2/D3):
* ``questions_gate_applies(repo)`` — whether the ORCH-120 priority+supersede
behaviour is REAL for this repo (kill-switch + scope, mirror of
``coverage_gate_applies``). OFF / out-of-scope -> ``stage_engine`` runs its
ORIGINAL byte-for-byte order (AC-9).
* ``autopause_applies(repo)`` — whether the engine auto-parks a task on Needs
Input (and unparks on resume). Independent sub-tumbler AND the questions gate
(a task is only ever auto-parked from within the questions-active branch).
* ``questions_active(worktree, work_item_id, files_ok)`` — the pure freshness-gated
supersede predicate (DQ-2): are there ACTIVE blocking questions that must win
over "files ready"?
never-raise contract (self-hosting safety): every public function degrades
conservatively and NEVER propagates into the stage engine / launcher / webhook.
"""
from __future__ import annotations
import logging
import os
from .config import settings
logger = logging.getLogger("orchestrator.analyst_questions")
# The analyst's signal artifact (DQ-4: path kept as-is; the engine already reads
# exactly this file — see stage_engine._handle_analysis_approved_flow).
QUESTIONS_FILENAME = "01-questions.md"
# The 4 mandatory analysis deliverables that ``check_analysis_complete`` gates on.
# Used by the mtime freshness-supersede check (DQ-2): a full FRESH package
# supersedes a stale, untouched 01-questions.md left over from a prior run.
DELIVERABLES = (
"01-brd.md",
"02-trz.md",
"03-acceptance-criteria.md",
"04-test-plan.yaml",
)
# ---------------------------------------------------------------------------
# Conditionality (mirrors coverage_gate_applies / serial_gate_applies)
# ---------------------------------------------------------------------------
def questions_gate_applies(repo: str) -> bool:
"""Whether the ORCH-120 questions priority+supersede is REAL for this repo.
Mirrors the ORCH-22 / ORCH-27 / ORCH-43 pattern:
* ``analyst_questions_gate_enabled=False`` -> always False (kill-switch; the
engine runs its ORIGINAL pre-ORCH-120 branch order — zero regression, AC-9).
* ``analyst_questions_gate_repos`` (CSV) non-empty -> real only for the listed
repos.
* empty CSV -> real ONLY for the self-hosting repo (``orchestrator``).
Never raises (AC-10): any error -> False (the safe no-op default that matches
the kill-switch-off behaviour).
"""
try:
if not getattr(settings, "analyst_questions_gate_enabled", False):
return False
raw = (getattr(settings, "analyst_questions_gate_repos", "") or "").strip()
if raw:
allowed = {r.strip().lower() for r in raw.split(",") if r.strip()}
return (repo or "").strip().lower() in allowed
# Lazy import keeps this module a leaf (no qg import at module load).
from .qg.checks import is_self_hosting_repo
return is_self_hosting_repo(repo)
except Exception as e: # noqa: BLE001 - never-raise contract
logger.warning("questions_gate_applies error for %s: %s", repo, e)
return False
def autopause_applies(repo: str) -> bool:
"""Whether the engine auto-parks on Needs Input / unparks on resume (D4/D5).
Two independent conditions, BOTH required:
* ``analyst_needs_input_autopause_enabled`` (independent sub-tumbler; False ->
operator-park only, via ``POST /serial-gate/pause``), AND
* ``questions_gate_applies(repo)`` — a task is only ever auto-parked from
within the questions-active branch, so the auto-park scope can never exceed
the questions gate (keeps the off/out-of-scope path byte-for-byte, AC-9).
Never raises (AC-10): any error -> False (degrade to operator-park).
"""
try:
if not getattr(settings, "analyst_needs_input_autopause_enabled", False):
return False
return questions_gate_applies(repo)
except Exception as e: # noqa: BLE001 - never-raise contract
logger.warning("autopause_applies error for %s: %s", repo, e)
return False
# ---------------------------------------------------------------------------
# Pure freshness-gated supersede predicate (DQ-2)
# ---------------------------------------------------------------------------
def _work_item_dir(worktree_path: str, work_item_id: str) -> str:
return os.path.join(worktree_path, "docs", "work-items", work_item_id)
def questions_active(worktree_path: str, work_item_id: str, files_ok: bool) -> bool:
"""Are there ACTIVE blocking questions that must win over "files ready" (DQ-2)?
Deterministic and OFFLINE (filesystem only — no network, no git):
* ``01-questions.md`` absent -> NOT active (``False``).
* package incomplete (``files_ok is False``) and the file is present -> active
(``True``): questions exist, deliverables do not -> questions win (AC-2).
* package complete (``files_ok is True``) and the file is present -> freshness
check: **superseded iff ALL 4 deliverables are strictly newer** than
``01-questions.md`` (by ``os.path.getmtime``). Superseded -> NOT active
(``False`` -> In Review, AC-6); otherwise -> active (``True`` -> Needs Input,
AC-1). A full FRESH analyst run always writes the 4 deliverables with a newer
mtime, so a stale untouched 01-questions.md is deterministically superseded
without depending on any LLM action.
Fail directions (never-raise, AC-10 / DQ-2):
* a ``getmtime``/comparison error while the file PROVABLY exists -> treat
questions as **active** (``True``, Needs Input) — safe for "don't build on
guesses".
* a catastrophic error (cannot even determine file presence) -> ``False`` so
``stage_engine`` degrades to its prior ``files_ok`` order + WARNING.
"""
try:
questions_path = os.path.join(
_work_item_dir(worktree_path, work_item_id), QUESTIONS_FILENAME
)
present = os.path.isfile(questions_path)
except Exception as e: # noqa: BLE001 - catastrophic: cannot determine presence
logger.warning(
"questions_active: cannot determine 01-questions.md presence for %s: %s",
work_item_id, e,
)
return False
if not present:
return False
if not files_ok:
# Questions present, deliverables incomplete -> questions take priority.
return True
# Package complete: superseded iff every deliverable is strictly newer than
# the questions file. Any mtime error on a proven-existing file -> active.
try:
q_mtime = os.path.getmtime(questions_path)
base = _work_item_dir(worktree_path, work_item_id)
for name in DELIVERABLES:
dp = os.path.join(base, name)
if not os.path.isfile(dp) or not (os.path.getmtime(dp) > q_mtime):
# A deliverable is missing or not strictly newer -> NOT superseded
# -> questions still active (Needs Input). (files_ok True means the
# gate saw all 4; a missing file here is defensive only.)
return True
# All 4 deliverables strictly newer -> superseded -> In Review.
return False
except Exception as e: # noqa: BLE001 - mtime error on existing file -> active
logger.warning(
"questions_active: freshness check failed for %s -> active (Needs Input): %s",
work_item_id, e,
)
return True

View File

@@ -1029,40 +1029,6 @@ class Settings(BaseSettings):
serial_gate_freeze_enabled: bool = True
serial_gate_pause_enabled: bool = True
# ORCH-120 (adr-0053): analyst open-questions -> Needs Input. Activates and
# completes the dead "analyst asks BLOCKING questions -> 01-questions.md ->
# Needs Input" path in _handle_analysis_approved_flow. Additive, never-raise,
# self-hosting scope; STAGE_TRANSITIONS / QG_CHECKS / check_* / machine-verdict
# keys / DB schema are byte-for-byte UNCHANGED (the flow is a pre-gate engine
# branch, NOT a Quality Gate; 01-questions.md is a SIGNAL artifact, NOT a
# machine-verdict). See docs/work-items/ORCH-120/06-adr/ADR-001-analyst-open-
# questions-needs-input.md.
# analyst_questions_gate_enabled -> kill-switch (env
# ORCH_ANALYST_QUESTIONS_GATE_ENABLED) of the
# priority+supersede behaviour (D3). False ->
# _handle_analysis_approved_flow runs its ORIGINAL
# pre-ORCH-120 order (files_ok first, then a flat
# isfile(01-questions.md) check) byte-for-byte (AC-9).
# analyst_questions_gate_repos -> CSV scope (env
# ORCH_ANALYST_QUESTIONS_GATE_REPOS). Empty -> real
# ONLY for the self-hosting repo (orchestrator) via
# is_self_hosting_repo; non-empty -> membership.
# Mirrors coverage_gate_repos -> enduro untouched.
# analyst_needs_input_autopause_enabled -> independent sub-tumbler (env
# ORCH_ANALYST_NEEDS_INPUT_AUTOPAUSE_ENABLED) for
# auto-park on Needs Input / unpark on resume (D4/D5)
# via the ORCH-124 pause axis (db.set_task_paused /
# clear_task_paused). True -> a Needs-Input task is
# excluded from the serial-gate "active task"
# predicate so the repo FIFO does not wedge while we
# wait for a human. False -> operator-park only
# (POST /serial-gate/pause). Subordinate to the
# questions gate (auto-park only fires from the
# questions-active branch).
analyst_questions_gate_enabled: bool = True
analyst_questions_gate_repos: str = ""
analyst_needs_input_autopause_enabled: bool = True
# ORCH-090: STOP-status task cancellation (stop active agent + full progress
# reset) and the relaunch-hole close. A new logical Plane key `stop` (fail-closed,
# absent from _DEFAULT_STATES) routes to a cancel handler that drives the task to
@@ -1196,51 +1162,6 @@ 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 = ""

258
src/db.py
View File

@@ -123,16 +123,6 @@ 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
@@ -306,39 +296,6 @@ 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()
@@ -599,204 +556,6 @@ 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()]
@@ -903,7 +662,6 @@ 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.
@@ -918,14 +676,6 @@ 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()
@@ -938,11 +688,9 @@ 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, "
"description) "
"VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
(plane_id, work_item_id, repo, branch, stage, plane_id, title,
description),
"(plane_id, work_item_id, repo, branch, stage, plane_issue_id, title) "
"VALUES (?, ?, ?, ?, ?, ?, ?)",
(plane_id, work_item_id, repo, branch, stage, plane_id, title),
)
conn.commit()
row = conn.execute(

View File

@@ -1,444 +0,0 @@
"""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

View File

@@ -269,7 +269,6 @@ 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 {
@@ -328,11 +327,6 @@ 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).
@@ -592,52 +586,6 @@ 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

View File

@@ -479,20 +479,6 @@ 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.

View File

@@ -156,14 +156,6 @@ _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",
@@ -963,23 +955,6 @@ 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).
@@ -1104,125 +1079,6 @@ 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)

View File

@@ -30,7 +30,7 @@ import os
import time
from dataclasses import dataclass, field
from .db import get_db, update_task_stage, enqueue_job, get_task_track, set_task_paused
from .db import get_db, update_task_stage, enqueue_job, get_task_track
from .stages import get_next_stage, get_qg_for_stage, get_agent_for_stage
from .git_worktree import get_worktree_path
from .review_parse import extract_review_findings, extract_test_failures
@@ -42,7 +42,6 @@ from . import post_deploy
from . import labels
from . import bug_fast_track
from . import transition_lease
from . import analyst_questions
from .notifications import (
notify_stage_change,
notify_qg_failure,
@@ -544,20 +543,6 @@ 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
@@ -723,195 +708,84 @@ def _handle_analysis_approved_flow(
return
files_ok, _ = files_check(repo, work_item_id, branch)
# ORCH-120 (adr-0053 D3): decide the analyst outcome — 'needs-input' |
# 'in-review' | 'empty'. When the questions-gate applies, ACTIVE blocking
# questions (01-questions.md, freshness-supersede aware, D2) take PRIORITY over
# "files ready" (a fabricated full package must not bury the analyst's blocking
# questions, AC-1). Under the kill-switch off / out-of-scope repo the ORIGINAL
# pre-ORCH-120 order runs byte-for-byte (files_ok first, then a flat
# isfile(01-questions.md) check) — zero regression (AC-9). never-raise (AC-10):
# on any error the decision degrades to that original order.
outcome = _decide_analysis_outcome(repo, work_item_id, branch, files_ok)
if outcome == "needs-input":
_emit_analysis_needs_input(task_id, repo, work_item_id, branch, result)
return
if outcome == "in-review":
_emit_analysis_in_review(
task_id, current_stage, repo, work_item_id, branch, result
)
return
_emit_analysis_empty(work_item_id, result)
def _decide_analysis_outcome(repo, work_item_id, branch, files_ok) -> str:
"""ORCH-120 (adr-0053 D3): 3-way decision for the analyst outcome.
Returns ``'needs-input'`` | ``'in-review'`` | ``'empty'``. never-raise (AC-10):
on any error degrade to the ORIGINAL pre-ORCH-120 order so behaviour is
byte-for-byte the same when the gate is off / out of scope.
"""
try:
worktree = get_worktree_path(repo, branch)
except Exception: # noqa: BLE001 - never-raise; treat as no worktree
worktree = ""
# Questions-gate ON: blocking questions take priority over files_ok (D3).
try:
gate_on = analyst_questions.questions_gate_applies(repo)
except Exception: # noqa: BLE001
gate_on = False
if gate_on:
active = None # None == predicate could not decide -> degrade below
try:
active = analyst_questions.questions_active(
worktree, work_item_id, files_ok
)
except Exception as e: # noqa: BLE001 - never-raise; degrade to original order
logger.warning(
f"questions_active failed for {work_item_id} -> "
f"degrade to original order: {e}"
)
active = None
if active is True:
return "needs-input"
if active is False:
return "in-review" if files_ok else "empty"
# active is None: predicate degraded -> fall through to the ORIGINAL order.
# Kill-switch off / out-of-scope / degraded: ORIGINAL byte-for-byte order
# (files_ok first, then a flat isfile(01-questions.md) check).
if files_ok:
return "in-review"
try:
questions_path = os.path.join(
worktree, f"docs/work-items/{work_item_id}/01-questions.md"
)
if worktree and os.path.isfile(questions_path):
return "needs-input"
except Exception: # noqa: BLE001 - never-raise
pass
return "empty"
def _emit_analysis_in_review(
task_id, current_stage, repo, work_item_id, branch, result: AdvanceResult
):
"""Full artifacts ready -> In Review + request the Approved STATUS (BUG C).
Carries the ORCH-089 autoApprove insertion verbatim. Extracted from
``_handle_analysis_approved_flow`` by ORCH-120 (D3) so the questions-priority
decision can dispatch here without changing this branch's behaviour.
"""
# Full artifacts ready -> In Review, ask for the Approved STATUS (BUG C).
set_issue_in_review(work_item_id)
plane_add_comment(
work_item_id,
# task_id is threaded through so build_status_comment can resolve the
# analyst duration via agent_runs (ORCH-016 AC-14 DB fallback).
_build_analyst_ready_comment(repo, work_item_id, branch, task_id=task_id),
author="analyst",
)
notify_approve_requested(task_id)
result.note = "analysis-in-review"
logger.info(
f"Task {task_id}: analyst finished, requested Approved status in Plane"
)
# --- ORCH-089 autoApprove: auto-pass the BRD human gate by label --------
# After In Review + the analyst comment + the approve-request (kept for the
# BRD-review clock, transparency and symmetry with the manual path), if the
# issue carries the autoApprove label AND the repo is in scope, auto-advance
# via the SAME path a human Approved takes — never duplicating the
# transition logic. applies() (local, network-free) is checked FIRST so a
# disabled kill-switch / out-of-scope repo costs zero network (AC-8); any
# error / no-label -> fall through to the prior behaviour (return, wait for
# a human, AC-4/AC-6).
if labels.auto_approve_applies(repo) and labels.has_label(
work_item_id, settings.auto_approve_label
):
set_issue_approved(work_item_id) # indication (AC-1), transient
logger.info(
f"Task {task_id}: label {settings.auto_approve_label} -> "
f"BRD auto-approved (analysis -> architecture)"
)
# Full artifacts ready -> In Review, ask for the Approved STATUS (BUG C).
set_issue_in_review(work_item_id)
plane_add_comment(
work_item_id,
f"✅ BRD авто-подтверждён (лейбл {settings.auto_approve_label}). "
"Переход на architecture без ручного Approved.",
# task_id is threaded through so build_status_comment can resolve the
# analyst duration via agent_runs (ORCH-016 AC-14 DB fallback).
_build_analyst_ready_comment(repo, work_item_id, branch, task_id=task_id),
author="analyst",
)
notify_approve_requested(task_id)
result.note = "analysis-in-review"
logger.info(
f"Task {task_id}: analyst finished, requested Approved status in Plane"
)
# --- ORCH-089 autoApprove: auto-pass the BRD human gate by label --------
# After In Review + the analyst comment + the approve-request (kept for the
# BRD-review clock, transparency and symmetry with the manual path), if the
# issue carries the autoApprove label AND the repo is in scope, auto-advance
# via the SAME path a human Approved takes — never duplicating the
# transition logic. applies() (local, network-free) is checked FIRST so a
# disabled kill-switch / out-of-scope repo costs zero network (AC-8); any
# error / no-label -> fall through to the prior behaviour (return, wait for
# a human, AC-4/AC-6).
if labels.auto_approve_applies(repo) and labels.has_label(
work_item_id, settings.auto_approve_label
):
set_issue_approved(work_item_id) # indication (AC-1), transient
logger.info(
f"Task {task_id}: label {settings.auto_approve_label} -> "
f"BRD auto-approved (analysis -> architecture)"
)
plane_add_comment(
work_item_id,
f"✅ BRD авто-подтверждён (лейбл {settings.auto_approve_label}). "
"Переход на architecture без ручного Approved.",
author="analyst",
)
send_telegram(
f"{link_for(work_item_id)}: BRD авто-подтверждён "
f"(лейбл {settings.auto_approve_label})."
)
# Same advance the human Approved webhook uses: finished_agent=None ->
# check_analysis_approved approved-via-status -> advance analysis ->
# architecture + mark_brd_review_ended (clock) + standard post-effects.
# Re-entrancy is safe: the nested call passes finished_agent=None, so it
# does NOT re-enter this analyst branch (which requires agent=='analyst').
auto = advance_stage(
task_id, current_stage, repo, work_item_id, branch, finished_agent=None
)
result.advanced = auto.advanced
result.to_stage = auto.to_stage
result.enqueued_agent = auto.enqueued_agent
result.enqueued_job_id = auto.enqueued_job_id
result.note = "auto-approved-via-label"
return
questions_path = os.path.join(
get_worktree_path(repo, branch),
f"docs/work-items/{work_item_id}/01-questions.md",
)
if os.path.isfile(questions_path):
set_issue_needs_input(work_item_id)
with open(questions_path, "r") as qf:
questions_text = qf.read()
plane_add_comment(
work_item_id,
f"\u2753 Analyst \u043d\u0443\u0436\u0434\u0430\u0435\u0442\u0441\u044f \u0432 \u0443\u0442\u043e\u0447\u043d\u0435\u043d\u0438\u0438:\n\n{questions_text}",
author="analyst",
)
send_telegram(
f" {link_for(work_item_id)}: BRD авто-подтверждён "
f"(лейбл {settings.auto_approve_label})."
f"\u2753 {link_for(work_item_id)}: Analyst \u0437\u0430\u0434\u0430\u0451\u0442 \u0432\u043e\u043f\u0440\u043e\u0441\u044b. \u041e\u0442\u0432\u0435\u0442\u044c \u0432 Plane."
)
# Same advance the human Approved webhook uses: finished_agent=None ->
# check_analysis_approved approved-via-status -> advance analysis ->
# architecture + mark_brd_review_ended (clock) + standard post-effects.
# Re-entrancy is safe: the nested call passes finished_agent=None, so it
# does NOT re-enter this analyst branch (which requires agent=='analyst').
auto = advance_stage(
task_id, current_stage, repo, work_item_id, branch, finished_agent=None
)
result.advanced = auto.advanced
result.to_stage = auto.to_stage
result.enqueued_agent = auto.enqueued_agent
result.enqueued_job_id = auto.enqueued_job_id
result.note = "auto-approved-via-label"
result.note = "analysis-needs-input"
return
def _emit_analysis_needs_input(
task_id, repo, work_item_id, branch, result: AdvanceResult
):
"""Blocking questions -> Needs Input + Plane comment + Telegram + auto-park.
The Plane comment / Telegram are preserved verbatim from the original
``_handle_analysis_approved_flow`` questions branch. ORCH-120 (D4) adds the
auto-park: when ``autopause_applies(repo)`` the task is parked
(``db.set_task_paused``) so the repo's serial-gate FIFO is not wedged while we
wait for a human (BR-3 / AC-4). never-raise (AC-10): a file-read or park error
degrades safely and never crashes ``advance_stage``.
"""
set_issue_needs_input(work_item_id)
questions_text = ""
try:
questions_path = os.path.join(
get_worktree_path(repo, branch),
f"docs/work-items/{work_item_id}/01-questions.md",
)
with open(questions_path, "r") as qf:
questions_text = qf.read()
except Exception as e: # noqa: BLE001 - never-raise; comment without body
logger.warning(
f"Task {task_id}: could not read 01-questions.md for {work_item_id}: {e}"
)
plane_add_comment(
work_item_id,
f"❓ Analyst нуждается в уточнении:\n\n{questions_text}",
author="analyst",
)
send_telegram(
f"{link_for(work_item_id)}: Analyst задаёт вопросы. Ответь в Plane."
)
# ORCH-120 (D4): auto-park via the ORCH-124 pause axis so the parked task stops
# holding the repo serial-gate FIFO. autopause_applies() is gated by the
# questions gate, so a kill-switch-off / out-of-scope repo never parks (AC-9).
# set_task_paused is already never-raise (-> False); the extra guard keeps a
# surprise from crashing advance_stage (AC-10). Park failure does NOT undo the
# Needs Input transition (degrades to operator-park, DQ-1).
try:
if analyst_questions.autopause_applies(repo) and set_task_paused(task_id):
logger.info(
f"Task {task_id}: auto-parked on Needs Input "
f"(serial-gate FIFO freed for {repo})"
)
except Exception as e: # noqa: BLE001 - never-raise
logger.warning(f"Task {task_id}: auto-park on Needs Input failed: {e}")
result.note = "analysis-needs-input"
def _emit_analysis_empty(work_item_id, result: AdvanceResult):
"""No artifacts and no questions — a warning comment (verbatim original)."""
# No artifacts and no questions.
plane_add_comment(
work_item_id,
"\u26a0\ufe0f Analyst \u0437\u0430\u0432\u0435\u0440\u0448\u0438\u043b\u0441\u044f \u0431\u0435\u0437 \u0430\u0440\u0442\u0435\u0444\u0430\u043a\u0442\u043e\u0432 \u0438 \u0431\u0435\u0437 \u0432\u043e\u043f\u0440\u043e\u0441\u043e\u0432. \u041f\u0440\u043e\u0432\u0435\u0440\u044c\u0442\u0435 \u043b\u043e\u0433.",

View File

@@ -166,18 +166,9 @@ 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:
@@ -267,86 +258,6 @@ 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.
@@ -444,26 +355,6 @@ async def handle_status_start(data: dict, project_id: str = ""):
logger.error(f"Failed to post relaunch-hole comment for {work_item_id}: {e}")
return
# ORCH-120 (adr-0053 D5): resume + unpark. The analyst (the sole Needs-Input
# owner, ORCH-066) was auto-parked on Needs Input (D4) so the repo serial-gate
# FIFO would not wedge while we waited for the stakeholder. Now that they
# answered and returned the issue to a working status, clear the pause so the
# re-enqueued analyst-job is claimable (jointly with the ORCH-126 stale
# run_id/pid fix). Gated on `analysis` + autopause_applies (questions gate +
# scope) so off/out-of-scope is byte-for-byte unchanged (AC-9); idempotent and
# never-raise — a resume that was never parked is a no-op.
if current_stage == "analysis":
try:
from .. import analyst_questions
from ..db import clear_task_paused
if analyst_questions.autopause_applies(repo) and clear_task_paused(task_id):
logger.info(
f"Task {task_id}: unparked on analyst resume "
f"(serial-gate FIFO re-entered for {repo})"
)
except Exception as e: # noqa: BLE001 - never-raise: resume must not crash
logger.warning(f"Task {task_id}: unpark on resume failed: {e}")
task_desc = (
f"Work item: {work_item_id}\nRepo: {repo}\nBranch: {branch}\n"
f"Stage: {current_stage}\nNote: Stakeholder returned the issue to In "
@@ -746,12 +637,8 @@ 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, description
plane_id, work_item_id, repo, branch, "analysis", name
)
if not created:
logger.info(
@@ -819,10 +706,8 @@ 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, description)
await _create_initial_docs(repo, branch, work_item_id, name)
except Exception as e:
logger.error(f"Failed to create initial docs: {e}")
else:
@@ -1029,59 +914,15 @@ async def _create_gitea_branch(repo: str, branch: str):
logger.info(f"Created branch '{branch}' in {owner}/{repo}")
# 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).
"""
async def _create_initial_docs(repo: str, branch: str, work_item_id: str, name: str):
"""Create initial business request doc in the feature branch."""
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 = _render_business_request(work_item_id, name, description)
content = f"# Business Request: {name}\n\nWork Item ID: {work_item_id}\n\n## Description\n\nTBD\n"
encoded = base64.b64encode(content.encode()).decode()
payload = {

View File

@@ -282,27 +282,6 @@ def test_reviewer_carries_overview_docs_axis():
)
def test_orch120_analyst_documents_questions_channel():
"""ORCH-120 (adr-0053) TC-07 (AC-7): analyst.md documents the 01-questions.md
Needs-Input channel (blocking questions -> Needs Input, do NOT fabricate
deliverables) without breaking the 52d canon (guarded by the canon tests above).
Anchored explicitly so a future prompt refactor cannot silently drop the
working contract (the same anti-drift rationale as the traceability axis)."""
text = _read("analyst")
assert "01-questions.md" in text, (
"analyst.md does not document the 01-questions.md Needs-Input channel"
)
assert "Needs Input" in text, (
"analyst.md does not tie 01-questions.md to the Needs Input outcome"
)
# Must instruct NOT to fabricate deliverables (the core BR-1 contract).
assert "фабрик" in text, (
"analyst.md does not carry the 'do not fabricate deliverables' instruction"
)
assert "ORCH-120" in text, "analyst.md does not anchor the questions channel to ORCH-120"
def test_reviewer_overview_axis_covers_system_showcase():
"""ORCH-011 (ADR-001 D7): the ORCH-079 overview-docs axis explicitly extends
to the system showcase `docs/overview/` — a PR changing functionality described

View File

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

View File

@@ -1,291 +0,0 @@
"""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}"
)

View File

@@ -367,19 +367,17 @@ def test_plane_canon_is_linked_not_forked():
def test_status_count_claim_matches_plane_sync():
"""Сверка импортом (не строковой копией): заявление дока «23 статуса»
держится фактическим маппингом src/plane_sync.py (нулевой дрейф, AC-6).
ORCH-020 добавил 23-й статус «Оценка» (триггер оценки задачи)."""
"""Сверка импортом (не строковой копией): заявление дока «22 статуса»
держится фактическим маппингом src/plane_sync.py (нулевой дрейф, AC-6)."""
from src.plane_sync import _PLANE_NAME_TO_KEY
assert len(_PLANE_NAME_TO_KEY) == 23, (
assert len(_PLANE_NAME_TO_KEY) == 22, (
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 "Оценка" in _PLANE_NAME_TO_KEY
assert "23" in _doc_text(), "число статусов в LITE_SETUP.md разъехалось с plane_sync"
assert "22" in _doc_text(), "число статусов в LITE_SETUP.md разъехалось с plane_sync"
def test_env_map_and_smoke_are_linked_to_replication():

View File

@@ -1,557 +0,0 @@
"""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

View File

@@ -1,263 +0,0 @@
"""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)

View File

@@ -1,305 +0,0 @@
"""ORCH-120 (adr-0053): analyst open-questions -> Needs Input — engine flow.
Drives ``_handle_analysis_approved_flow`` through the real ``advance_stage(...,
finished_agent='analyst')`` launcher path (pattern of
``tests/test_auto_approve_brd.py``): mocks the Plane/Telegram setters and uses a
temporary worktree + a patched ``check_analysis_complete``.
Covers (04-test-plan.yaml):
TC-01 REGRESS (mandatory): 4 files + ACTIVE 01-questions.md simultaneously ->
Needs Input wins over "files ready" (AC-1). RED before the fix.
TC-02 01-questions.md present, 4 files missing -> Needs Input, question text in
the Plane comment + Telegram (AC-2).
TC-03 Happy-path: no 01-questions.md, 4 files present -> In Review (AC-3).
TC-06 Hygiene: full FRESH package supersedes a stale 01-questions.md -> In
Review, NOT a repeat Needs Input (AC-6).
TC-09 never-raise: a failure in the new logic degrades safely + does not crash
advance_stage (AC-10).
TC-10 Reversibility: kill-switch off OR enduro repo -> ORIGINAL byte-for-byte
order (files_ok first) (AC-9).
"""
import os
import tempfile
import pytest
_test_db = os.path.join(tempfile.gettempdir(), "test_orch120_needs_input.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")
from unittest.mock import MagicMock # noqa: E402
import src.db as _db # noqa: E402
from src.db import init_db, get_db # noqa: E402
from src import stage_engine # noqa: E402
from src import analyst_questions # noqa: E402
from src import labels # noqa: E402
from src.config import settings # noqa: E402
from src.stage_engine import advance_stage # noqa: E402
_DELIVERABLES = ("01-brd.md", "02-trz.md", "03-acceptance-criteria.md", "04-test-plan.yaml")
@pytest.fixture(autouse=True)
def fresh(monkeypatch, tmp_path):
monkeypatch.setattr(_db.settings, "db_path", _test_db)
if os.path.exists(_test_db):
os.unlink(_test_db)
init_db()
# Silence Plane/Telegram side effects; capture the channels we assert on.
for name in ("notify_stage_change", "notify_qg_failure", "plane_notify_stage",
"plane_notify_qg", "set_issue_in_review", "set_issue_needs_input",
"set_issue_approved", "notify_approve_requested"):
monkeypatch.setattr(stage_engine, name, MagicMock(), raising=False)
monkeypatch.setattr(stage_engine, "_build_analyst_ready_comment",
lambda *a, **k: "ready", raising=False)
monkeypatch.setattr(stage_engine, "plane_add_comment", MagicMock())
monkeypatch.setattr(stage_engine, "send_telegram", MagicMock())
# autoApprove off by default (TC-03 wants In Review, not auto-advance).
monkeypatch.setattr(labels, "auto_approve_applies", lambda repo: False)
monkeypatch.setattr(labels, "has_label", lambda w, name, p=None: False)
# Questions-gate on for orchestrator by default (mirror prod defaults).
monkeypatch.setattr(settings, "analyst_questions_gate_enabled", True, raising=False)
monkeypatch.setattr(settings, "analyst_questions_gate_repos", "", raising=False)
monkeypatch.setattr(settings, "analyst_needs_input_autopause_enabled", True,
raising=False)
yield
def _make_task(stage="analysis", repo="orchestrator", branch="feature/ORCH-120-x",
wi="ORCH-120"):
conn = get_db()
cur = conn.execute(
"INSERT INTO tasks (plane_id, work_item_id, repo, branch, stage) "
"VALUES (?, ?, ?, ?, ?)",
(f"plane-{wi}", wi, repo, branch, stage),
)
tid = cur.lastrowid
conn.commit()
conn.close()
return tid
def _wi_dir(worktree, wi="ORCH-120"):
d = os.path.join(worktree, "docs", "work-items", wi)
os.makedirs(d, exist_ok=True)
return d
def _write(path, mtime=None, body="x"):
with open(path, "w") as f:
f.write(body)
if mtime is not None:
os.utime(path, (mtime, mtime))
def _patch_worktree(monkeypatch, worktree):
monkeypatch.setattr(stage_engine, "get_worktree_path", lambda repo, branch: worktree)
def _patch_complete_gate(monkeypatch, ok=True):
def gate(*a, **k):
return (ok, "ok" if ok else "missing artifacts")
monkeypatch.setattr(
stage_engine, "QG_CHECKS",
{**stage_engine.QG_CHECKS, "check_analysis_complete": gate},
)
def _stage_of(task_id):
conn = get_db()
row = conn.execute("SELECT stage FROM tasks WHERE id=?", (task_id,)).fetchone()
conn.close()
return row[0]
def _paused_at(task_id):
conn = get_db()
row = conn.execute("SELECT paused_at FROM tasks WHERE id=?", (task_id,)).fetchone()
conn.close()
return row[0]
# --- TC-01: REGRESS — questions priority over files_ok -----------------------
def test_tc01_questions_priority_over_files_ready(monkeypatch, tmp_path):
"""4 deliverables + an ACTIVE (newest) 01-questions.md -> Needs Input wins."""
worktree = str(tmp_path)
d = _wi_dir(worktree)
base = 1_000_000
for i, name in enumerate(_DELIVERABLES):
_write(os.path.join(d, name), mtime=base + i)
# 01-questions.md is the NEWEST -> NOT superseded -> active.
_write(os.path.join(d, "01-questions.md"), mtime=base + 100,
body="Q-1 нужно уточнить охват")
_patch_worktree(monkeypatch, worktree)
_patch_complete_gate(monkeypatch, ok=True)
tid = _make_task()
res = advance_stage(tid, "analysis", "orchestrator", "ORCH-120",
"feature/ORCH-120-x", finished_agent="analyst")
assert res.note == "analysis-needs-input"
assert stage_engine.set_issue_needs_input.called
assert not stage_engine.set_issue_in_review.called
assert _stage_of(tid) == "analysis" # NOT advanced to architecture
# --- TC-02: questions only, no deliverables ----------------------------------
def test_tc02_questions_only_no_deliverables(monkeypatch, tmp_path):
worktree = str(tmp_path)
d = _wi_dir(worktree)
_write(os.path.join(d, "01-questions.md"), body="Q-1 какой формат вывода?")
_patch_worktree(monkeypatch, worktree)
_patch_complete_gate(monkeypatch, ok=False)
tid = _make_task()
res = advance_stage(tid, "analysis", "orchestrator", "ORCH-120",
"feature/ORCH-120-x", finished_agent="analyst")
assert res.note == "analysis-needs-input"
assert stage_engine.set_issue_needs_input.called
# Question text reached the Plane comment + Telegram.
comment_arg = stage_engine.plane_add_comment.call_args.args[1]
assert "Q-1 какой формат вывода?" in comment_arg
assert stage_engine.send_telegram.called
# --- TC-03: happy-path, no questions -----------------------------------------
def test_tc03_happy_path_no_questions(monkeypatch, tmp_path):
worktree = str(tmp_path)
d = _wi_dir(worktree)
for name in _DELIVERABLES:
_write(os.path.join(d, name))
# No 01-questions.md.
_patch_worktree(monkeypatch, worktree)
_patch_complete_gate(monkeypatch, ok=True)
tid = _make_task()
res = advance_stage(tid, "analysis", "orchestrator", "ORCH-120",
"feature/ORCH-120-x", finished_agent="analyst")
assert res.note == "analysis-in-review"
assert stage_engine.set_issue_in_review.called
assert not stage_engine.set_issue_needs_input.called
assert stage_engine.notify_approve_requested.called
# --- TC-06: hygiene — fresh package supersedes a stale questions file --------
def test_tc06_stale_questions_superseded(monkeypatch, tmp_path):
worktree = str(tmp_path)
d = _wi_dir(worktree)
base = 2_000_000
# 01-questions.md is OLDER than every deliverable -> superseded -> In Review.
_write(os.path.join(d, "01-questions.md"), mtime=base, body="stale Q from last run")
for i, name in enumerate(_DELIVERABLES):
_write(os.path.join(d, name), mtime=base + 100 + i)
_patch_worktree(monkeypatch, worktree)
_patch_complete_gate(monkeypatch, ok=True)
tid = _make_task()
res = advance_stage(tid, "analysis", "orchestrator", "ORCH-120",
"feature/ORCH-120-x", finished_agent="analyst")
assert res.note == "analysis-in-review"
assert stage_engine.set_issue_in_review.called
assert not stage_engine.set_issue_needs_input.called
# --- TC-09: never-raise -------------------------------------------------------
def test_tc09_predicate_error_degrades_to_prior_order(monkeypatch, tmp_path):
"""questions_active raising -> degrade to original order (files_ok -> In Review)."""
worktree = str(tmp_path)
_wi_dir(worktree)
_patch_worktree(monkeypatch, worktree)
_patch_complete_gate(monkeypatch, ok=True)
def boom(*a, **k):
raise RuntimeError("synthetic predicate failure")
monkeypatch.setattr(analyst_questions, "questions_active", boom)
tid = _make_task()
# Must NOT raise.
res = advance_stage(tid, "analysis", "orchestrator", "ORCH-120",
"feature/ORCH-120-x", finished_agent="analyst")
assert res.note == "analysis-in-review"
assert stage_engine.set_issue_in_review.called
def test_tc09_park_error_does_not_crash(monkeypatch, tmp_path):
"""A failing set_task_paused must not undo Needs Input nor crash advance_stage."""
worktree = str(tmp_path)
d = _wi_dir(worktree)
_write(os.path.join(d, "01-questions.md"), body="Q-1 ?")
_patch_worktree(monkeypatch, worktree)
_patch_complete_gate(monkeypatch, ok=False)
def boom(task_id):
raise RuntimeError("synthetic park failure")
monkeypatch.setattr(stage_engine, "set_task_paused", boom)
tid = _make_task()
res = advance_stage(tid, "analysis", "orchestrator", "ORCH-120",
"feature/ORCH-120-x", finished_agent="analyst")
assert res.note == "analysis-needs-input"
assert stage_engine.set_issue_needs_input.called
# --- TC-10: reversibility — kill-switch off / enduro -> original order --------
def test_tc10_kill_switch_off_original_order(monkeypatch, tmp_path):
"""Gate off: 4 files + active questions -> In Review (original order), no park."""
worktree = str(tmp_path)
d = _wi_dir(worktree)
base = 3_000_000
for i, name in enumerate(_DELIVERABLES):
_write(os.path.join(d, name), mtime=base + i)
_write(os.path.join(d, "01-questions.md"), mtime=base + 100, body="Q-1 ?")
_patch_worktree(monkeypatch, worktree)
_patch_complete_gate(monkeypatch, ok=True)
monkeypatch.setattr(settings, "analyst_questions_gate_enabled", False, raising=False)
tid = _make_task()
res = advance_stage(tid, "analysis", "orchestrator", "ORCH-120",
"feature/ORCH-120-x", finished_agent="analyst")
assert res.note == "analysis-in-review"
assert stage_engine.set_issue_in_review.called
assert not stage_engine.set_issue_needs_input.called
assert _paused_at(tid) is None # no auto-park when the gate is off
def test_tc10_enduro_out_of_scope_original_order(monkeypatch, tmp_path):
"""enduro repo (empty CSV -> self-hosting only) -> gate inert -> original order."""
worktree = str(tmp_path)
d = _wi_dir(worktree, wi="ET-9")
base = 4_000_000
for i, name in enumerate(_DELIVERABLES):
_write(os.path.join(d, name), mtime=base + i)
_write(os.path.join(d, "01-questions.md"), mtime=base + 100, body="Q-1 ?")
_patch_worktree(monkeypatch, worktree)
_patch_complete_gate(monkeypatch, ok=True)
tid = _make_task(repo="enduro-trails", branch="feature/ET-9-x", wi="ET-9")
res = advance_stage(tid, "analysis", "enduro-trails", "ET-9",
"feature/ET-9-x", finished_agent="analyst")
assert res.note == "analysis-in-review"
assert stage_engine.set_issue_in_review.called
assert not stage_engine.set_issue_needs_input.called
# --- Auto-park bonus: orchestrator Needs Input parks the task ----------------
def test_autopark_on_needs_input(monkeypatch, tmp_path):
"""ORCH-120 D4: Needs Input on the self-hosting repo auto-parks the task."""
worktree = str(tmp_path)
d = _wi_dir(worktree)
_write(os.path.join(d, "01-questions.md"), body="Q-1 ?")
_patch_worktree(monkeypatch, worktree)
_patch_complete_gate(monkeypatch, ok=False)
tid = _make_task()
advance_stage(tid, "analysis", "orchestrator", "ORCH-120",
"feature/ORCH-120-x", finished_agent="analyst")
assert _paused_at(tid) is not None # task parked -> serial-gate FIFO freed

View File

@@ -1,56 +0,0 @@
"""ORCH-120 (adr-0053) TC-08: canon of the 01-questions.md signal artifact.
Pure-text structural checks (NO src/ import): the skeleton exists and the
PIPELINE_DOCS.md manifest documents 01-questions.md as an analyst-owned,
when-applicable, NON-machine-verdict signal artifact (AC-8).
"""
import os
_REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
_TEMPLATE = os.path.join(_REPO_ROOT, "docs", "_templates", "01-questions.md")
_PIPELINE_DOCS = os.path.join(_REPO_ROOT, "docs", "_standards", "PIPELINE_DOCS.md")
def _read(path):
with open(path, encoding="utf-8") as f:
return f.read()
def test_questions_skeleton_exists_and_nonempty():
"""TC-08: docs/_templates/01-questions.md exists and is non-empty."""
assert os.path.isfile(_TEMPLATE), "docs/_templates/01-questions.md is missing"
body = _read(_TEMPLATE)
assert body.strip(), "01-questions.md template is empty"
# Carries the 52c schema fields + signals the analyst stage/owner.
for field in ("work_item", "stage", "author_agent", "status", "created_at",
"model_used"):
assert field in body, f"01-questions.md template omits schema field {field!r}"
assert "stage: analysis" in body
assert "author_agent: analyst" in body
# Documents the three required parts (context / blocking questions / unblocks).
assert "Блокирующие вопросы" in body
assert "разблокирует" in body
def test_pipeline_docs_manifest_row_for_questions():
"""TC-08: PIPELINE_DOCS.md has a manifest row for 01-questions.md."""
text = _read(_PIPELINE_DOCS)
# A manifest table row mentioning the file, the analyst owner and when-applicable.
rows = [ln for ln in text.splitlines()
if "`01-questions.md`" in ln and "|" in ln]
assert rows, "PIPELINE_DOCS.md has no manifest row for 01-questions.md"
row = rows[0]
assert "analyst" in row, "01-questions.md manifest row does not name the analyst owner"
assert "when-applicable" in row, "01-questions.md row not marked when-applicable"
# Signal artifact -> NOT a machine-verdict.
assert ("сигнальн" in row.lower()) or ("не machine-verdict" in row.lower()), (
"01-questions.md row does not mark it as a signal / non-machine-verdict artifact"
)
def test_pipeline_docs_notes_the_01_prefix_convention():
"""TC-08 (DQ-4): PIPELINE_DOCS.md notes the shared `01-` prefix convention."""
text = _read(_PIPELINE_DOCS)
assert "Префикс `01-`" in text or "префикс `01-`" in text, (
"PIPELINE_DOCS.md does not document the 01- prefix convention (DQ-4)"
)

View File

@@ -1,100 +0,0 @@
"""ORCH-120 (adr-0053) TC-05: resume + unpark on analyst relaunch.
When the stakeholder answers and returns the issue to a working status on
``analysis``, ``handle_status_start`` clears the auto-park (``paused_at`` -> NULL)
so the re-enqueued analyst-job is claimable, and relaunches the analyst. The
ORCH-090 relaunch-guard (relaunch only for ``analysis``) is not weakened.
TC-05 paused analysis task + To Analyse, no active job -> unpark + relaunch
analyst; relaunch-guard (analysis only) respected (AC-5).
"""
import os
import tempfile
import pytest
_test_db = os.path.join(tempfile.gettempdir(), "test_orch120_resume_unpark.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")
from unittest.mock import patch, AsyncMock, MagicMock # noqa: E402
import src.db as _db # noqa: E402
from src.db import init_db, get_db, set_task_paused, is_task_paused # noqa: E402
from src import config as cfg # noqa: E402
from src.webhooks.plane import handle_status_start # noqa: E402
@pytest.fixture(autouse=True)
def fresh(monkeypatch):
monkeypatch.setattr(_db.settings, "db_path", _test_db)
if os.path.exists(_test_db):
os.unlink(_test_db)
init_db()
# Questions gate + autopause ON for the self-hosting repo (prod defaults).
monkeypatch.setattr(cfg.settings, "analyst_questions_gate_enabled", True, raising=False)
monkeypatch.setattr(cfg.settings, "analyst_questions_gate_repos", "", raising=False)
monkeypatch.setattr(cfg.settings, "analyst_needs_input_autopause_enabled", True,
raising=False)
yield
if os.path.exists(_test_db):
os.unlink(_test_db)
def _make_task(plane_id, stage="analysis", repo="orchestrator", branch="feature/ORCH-120-x",
wi="ORCH-120"):
conn = get_db()
cur = conn.execute(
"INSERT INTO tasks (plane_id, work_item_id, repo, branch, stage) "
"VALUES (?, ?, ?, ?, ?)",
(plane_id, wi, repo, branch, stage),
)
tid = cur.lastrowid
conn.commit()
conn.close()
return tid
@pytest.mark.asyncio
async def test_tc05_resume_unparks_and_relaunches_analyst():
tid = _make_task("resume-120", stage="analysis")
assert set_task_paused(tid) is True
assert is_task_paused(tid) is True # parked while waiting for a human
data = {"id": "resume-120", "state": {"id": "ip-uuid", "name": "To Analyse"}}
with patch("src.webhooks.plane.enqueue_job", return_value=11) as mock_enqueue, \
patch("src.webhooks.plane.start_pipeline", new_callable=AsyncMock) as mock_start, \
patch("src.plane_sync.add_comment", MagicMock()), \
patch("src.plane_sync.set_issue_analysis") as mock_analysis:
await handle_status_start(data, "proj-1")
mock_start.assert_not_called() # resume, not a fresh pipeline
# Unparked: the re-enqueued analyst-job is claimable again (AC-5).
assert is_task_paused(tid) is False
# Analyst relaunched exactly once (relaunch-guard: only analysis, ORCH-090).
assert mock_enqueue.call_count == 1
assert mock_enqueue.call_args.args[0] == "analyst"
mock_analysis.assert_called_once_with("ORCH-120")
@pytest.mark.asyncio
async def test_tc05_autopause_off_does_not_unpark():
"""Reversibility: with the autopause sub-flag off the resume does not unpark
(operator-park stays the operator's to clear); relaunch still happens."""
tid = _make_task("resume-120b", stage="analysis")
set_task_paused(tid)
data = {"id": "resume-120b", "state": {"id": "ip-uuid", "name": "To Analyse"}}
with patch("src.config.settings.analyst_needs_input_autopause_enabled", False, create=True), \
patch("src.webhooks.plane.enqueue_job", return_value=12) as mock_enqueue, \
patch("src.webhooks.plane.start_pipeline", new_callable=AsyncMock), \
patch("src.plane_sync.add_comment", MagicMock()), \
patch("src.plane_sync.set_issue_analysis"):
await handle_status_start(data, "proj-1")
# Autopause off -> engine-side unpark is inert; the task stays parked (operator
# clears via POST /serial-gate/resume). The relaunch itself is unaffected.
assert is_task_paused(tid) is True
assert mock_enqueue.call_count == 1

View File

@@ -1,111 +0,0 @@
"""ORCH-120 (adr-0053) TC-04: Needs Input auto-park does not wedge serial-gate.
Integration: a self-hosting task A driven into Needs Input through the real
``advance_stage(..., finished_agent='analyst')`` path is auto-parked (D4), which
EXCLUDES it from the serial-gate "active task" predicate (ORCH-088/124) so a later
task B of the same repo can enter ``analysis`` (its analyst-job becomes claimable).
TC-04 earlier task A (analysis) blocks B's analyst-job; once A is driven into
Needs Input (auto-parked), B's analyst-job becomes claimable (AC-4).
"""
import os
import tempfile
import pytest
_test_db = os.path.join(tempfile.gettempdir(), "test_orch120_serial_gate.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")
from unittest.mock import MagicMock # noqa: E402
import src.db as _db # noqa: E402
from src.db import init_db, get_db, enqueue_job, claim_next_job # noqa: E402
from src import stage_engine # noqa: E402
from src import labels # noqa: E402
from src import config as cfg # noqa: E402
from src.stage_engine import advance_stage # noqa: E402
@pytest.fixture(autouse=True)
def fresh(monkeypatch, tmp_path):
monkeypatch.setattr(_db.settings, "db_path", _test_db)
if os.path.exists(_test_db):
os.unlink(_test_db)
init_db()
# Serial gate + pause axis ON (empty CSV -> all repos).
monkeypatch.setattr(cfg.settings, "serial_gate_enabled", True, raising=False)
monkeypatch.setattr(cfg.settings, "serial_gate_repos", "", raising=False)
monkeypatch.setattr(cfg.settings, "serial_gate_freeze_enabled", True, raising=False)
monkeypatch.setattr(cfg.settings, "serial_gate_pause_enabled", True, raising=False)
monkeypatch.setattr(cfg.settings, "task_deps_enabled", False, raising=False)
# Questions gate + autopause ON for orchestrator (prod defaults).
monkeypatch.setattr(cfg.settings, "analyst_questions_gate_enabled", True, raising=False)
monkeypatch.setattr(cfg.settings, "analyst_questions_gate_repos", "", raising=False)
monkeypatch.setattr(cfg.settings, "analyst_needs_input_autopause_enabled", True,
raising=False)
# Silence Plane/Telegram side effects.
for name in ("set_issue_in_review", "set_issue_needs_input", "set_issue_approved",
"notify_approve_requested", "plane_notify_stage"):
monkeypatch.setattr(stage_engine, name, MagicMock(), raising=False)
monkeypatch.setattr(stage_engine, "plane_add_comment", MagicMock())
monkeypatch.setattr(stage_engine, "send_telegram", MagicMock())
monkeypatch.setattr(labels, "auto_approve_applies", lambda repo: False)
monkeypatch.setattr(labels, "has_label", lambda w, name, p=None: False)
yield
def _make_task(wi, stage="analysis", repo="orchestrator"):
conn = get_db()
cur = conn.execute(
"INSERT INTO tasks (plane_id, work_item_id, repo, branch, stage) "
"VALUES (?, ?, ?, ?, ?)",
(wi, wi, repo, f"feature/{wi}", stage),
)
tid = cur.lastrowid
conn.commit()
conn.close()
return tid
def _paused_at(task_id):
conn = get_db()
row = conn.execute("SELECT paused_at FROM tasks WHERE id=?", (task_id,)).fetchone()
conn.close()
return row[0]
def test_tc04_needs_input_autopark_unblocks_serial_gate(monkeypatch, tmp_path):
a = _make_task("ORCH-120A", stage="analysis") # earlier active task
b = _make_task("ORCH-120B", stage="analysis") # later task awaiting analysis
job_b = enqueue_job("analyst", "orchestrator", "B", task_id=b)
# Before A is parked it holds the repo's FIFO gate -> B's analyst-job blocked.
assert claim_next_job() is None, "active A gates B (FIFO, ORCH-088)"
# Drive A into Needs Input via the engine (01-questions.md present, no
# deliverables) -> auto-park.
worktree = str(tmp_path)
d = os.path.join(worktree, "docs", "work-items", "ORCH-120A")
os.makedirs(d, exist_ok=True)
with open(os.path.join(d, "01-questions.md"), "w") as f:
f.write("Q-1 нужно уточнить охват")
monkeypatch.setattr(stage_engine, "get_worktree_path", lambda repo, br: worktree)
monkeypatch.setattr(
stage_engine, "QG_CHECKS",
{**stage_engine.QG_CHECKS,
"check_analysis_complete": lambda *a, **k: (False, "missing")},
)
res = advance_stage(a, "analysis", "orchestrator", "ORCH-120A",
"feature/ORCH-120A", finished_agent="analyst")
assert res.note == "analysis-needs-input"
assert _paused_at(a) is not None, "A must be auto-parked on Needs Input (D4)"
# Now the parked A no longer holds the FIFO gate -> B's analyst-job is claimable.
claimed = claim_next_job()
assert claimed is not None and claimed["id"] == job_b, (
"a parked Needs-Input predecessor must not wedge the repo serial-gate (AC-4)"
)

View File

@@ -68,9 +68,7 @@ async def _drive_start_pipeline(monkeypatch, gate_applies: bool):
async def _branch_spy(repo, branch):
branch_calls.append((repo, branch))
# 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):
async def _docs_spy(repo, branch, wi, name):
docs_calls.append((repo, branch, wi, name))
monkeypatch.setattr(plane, "_create_gitea_branch", _branch_spy)