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

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

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).

# 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).