190 lines
16 KiB
Markdown
190 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
|
||
---
|
||
|
||
# 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).
|
||
```
|