16 KiB
16 KiB
work_item, stage, author_agent, status, created_at, model_used
| work_item | stage | author_agent | status | created_at | model_used |
|---|---|---|---|---|---|
| ORCH-108 | analysis | analyst | ready-for-review | 2026-06-17 | 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):- Идемпотентно — отсутствующая или уже терминальная (
done/cancelled) задача → no-op. - Критичное окно (
src/cancel.py::in_critical_window) — задача в необратимой фазе merge/deploy → отложенная отмена (cancel_requested_at, снимаются толькоqueued-job'ы, алерт «⏸️ … отложена»; finalizer применяет отмену после честного завершения шага). STOP никогда не трогаетmain, не делает force-push, не рестартит прод-контейнер. - Полный сброс (вне критичного окна) — SIGTERM агента (graceful-каскад), все job'ы →
терминальный
cancelled, очистка deploy-state + освобождение merge-lease, снятие worktree, удаление рабочей Gitea-ветки (неmain, без force-push), тумбстон натуральных ключей +stage='cancelled'. Docs-артефакты сохраняются. - Наблюдаемость — 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 задачи риски минимальны).