182 lines
16 KiB
Markdown
182 lines
16 KiB
Markdown
---
|
||
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 задачи риски
|
||
минимальны).
|