jellybit/openspec/changes/archive/2026-08-06-cancel-dismiss-split-wording/design.md

Context

Аудит capability state-reconciliation (сверка код↔спека) нашёл расхождение в требовании «Ручное закрытие загрузки (стоп-кран)». Спека утверждает единый путь закрытия из любого состояния кроме deleted, помечаемый error_code = "user_dismiss". Код даёт два пути, разведённые по состояниям.

Что показало чтение кода (провенанс каждого факта — путь:строка):

Факт	Где
Cancel отклоняет терминальные состояния, ставит пустые error_code/error_msg	internal/worker/worker.go:973
Dismiss доступен из любого состояния кроме deleted, ставит user_dismiss, из cancelled — no-op без записи	internal/worker/worker.go:1001
Веб-UI: «Закрыть» только для терминальных, кроме deleted/cancelled	internal/httpapi/download.go:129
Веб-UI: «Отменить» только для не-терминальных	web/templates/partials/download_main.html:26, partials/card.html:32
Экран ревью: «Отклонить» → Cancel	web/templates/partials/review_main.html:77
Telegram: «Закрыть» на failed/stuck и на done/orphaned/target_missing	internal/tgbot/render.go:271, :290
Telegram: «Отклонить» → Cancel на карточке ревью	internal/tgbot/render.go:119, bot.go:325
Telegram: downloading/recognizing/linking/completed/catched — карточка без действий (только ссылка в веб)	internal/tgbot/render.go:39
REST: есть cancel и retry, dismiss нет	internal/httpapi/httpapi.go:152
failed терминален, stuck — нет	internal/store/download.go:54
Граф переходов уже описывает пару Cancel/Dismiss прозой	internal/store/download.go:86

Важное следствие таблицы: постановка задачи описывала разрыв как «веб-UI против домена», а он шире — раскладка путей разная у разных поверхностей. Telegram даёт Dismiss из stuck, то есть из не-терминального состояния, а на review даёт Cancel; веб-UI режет строго по терминальности.

Ограничение по постановке: кода изменение не трогает — критерий приёмки задачи требует пустого дифа под internal/ и web/.

Goals / Non-Goals

Goals:

• Нормативный дом поведения перестаёт утверждать то, чего поверхности не дают.
• Требование называет error_code на каждом пути закрытия, а не на одном.
• Требование называет гарантию, которая действительно держится: закрытие доступно из любого не-deleted состояния хотя бы одной поверхностью.
• Разрыв наблюдаемости назван с ценой, чтобы следующий аудит не открывал его заново.

Non-Goals:

• Не менять поведение: Dismiss из не-терминальных состояний веб-UI не зовётся, гейт Dismissable остаётся как есть.
• Не заводить второй ADR о приёме «спека следует за кодом» — приём уже описан в ADR-2026-08-06-spec-follows-code-on-narrow-window.
• Не переписывать требование review о команде «Отклонить»: его предмет — экран ревью, а не закрытие как класс.
• Не заводить dismiss в REST: REST помечен опциональным транспортом.

Decisions

D1. Спека двигается к коду — но только в той половине, где приём ADR применим

Приём и его границы заданы ADR-2026-08-06: двигается тот, чья формулировка сильнее рационали. Требование содержит два обещания, и приём применим только к одному из них — ревью предложения показало, что первая редакция этого не различала.

• Обещание доступности («закрыть можно любую загрузку кроме deleted»). Рациональ кодом выполнен: страница загрузки веб-UI даёт путь закрытия из каждого не-deleted, не-cancelled состояния. Формулировка «команда dismiss из любого состояния во всех транспортах» была сильнее рационали и требовала от каждой поверхности обе кнопки. Здесь спека и правда двигается к коду.
• Обещание различимости («закрытие помечено user_dismiss»). Рациональ — различать инициатора в диагностике — кодом не достигнут, а по правилу того же ADR недостающая гарантия чинится кодом. Поэтому спека этот пункт не закрепляет: сегодняшняя пустота кода на пути Cancel описана как факт, а не как SHALL, и вопрос оставлен открытым (D7).

Альтернатива C (оставить всё как есть) отвергается по тому же основанию, что в ADR: расхождение воспроизводится каждым аудитом, а читатель спеки считает маркер гарантированным.

D2. Требование разводит доменную команду и обязательства поверхностей

Прежний текст смешивал два уровня в одном предложении («команда доступна из любого состояния во всех транспортах»). Новый текст разводит: нормативны гарантия закрытия (страница загрузки веб-UI даёт путь из каждого не-deleted/cancelled состояния) и гейты доменных путей (Cancel — не-терминальные, Dismiss — всё кроме deleted). Раскладка кнопок по поверхностям нормативной не объявляется: она описана как сегодняшнее состояние, перечислением состояний, а не оборотом «там, где карточка вообще даёт действия».

Первая редакция закрепляла раскладку через SHALL, и ревью предложения нашло в этом две беды разом: она противоречила заявке этого же решения («спека фиксирует гарантию, не вёрстку»), а Telegram-половина формулировки была круговой — истинной при любом поведении кода, включая удаление кнопки. Описательная форма с перечнем состояний фальсифицируема (по ней строится таблица «состояние × поверхность») и не превращает будущее выравнивание поверхностей в нарушение спеки.

Альтернатива — перечислить в спеке точную раскладку клавиатур Telegram — отклонена: спека стала бы копией render.go и краснела бы от косметической правки кнопки.

D3. error_code называется на каждом пути; нормативен только user_dismiss

Пустой код — тоже наблюдаемое обязательство, и умолчание о нём породило задачу. Пишем прямо: Dismiss → "user_dismiss" (нормативно), Cancel → сегодня пусто (описательно, см. D1 и D7). К этому добавлено то, чего в старом тексте не было вовсе: оба пути замещают прежнюю диагностику записи. Первая редакция приписывала затирание только Cancel и тем создавала ложное впечатление, что маркерный путь причину сохраняет; worker.go:1016 пишет user_dismiss поверх qbit_error ровно так же.

D4. Ограничение названо в теле требования, а не спрятано в design

Форма взята из ADR-2026-08-06: молчащая ложная гарантия дороже названного ограничения. Абзац «известное ограничение» стоит в самом требовании, потому что архив change'а читают реже, чем спеку.

D5. review не трогаем

Команда «Отклонить» описана в review («Команды ревью и их эффекты», review/spec.md:33, :370) — там её дом. Здесь она упоминается как один из путей закрытия со ссылкой на состояние, но требование review не переписывается: иначе у одного факта появилось бы два нормативных дома.

Цена решения названа честно: error_code пути «Отклонить» теперь стоит в state-reconciliation, а сама команда описана в review. Разнесение оправдано тем, что предмет здесь — закрытие как класс, и сравнение двух путей имеет смысл только рядом.

D6. Сценарии добавляются на оба новых утверждения

Постановка требовала сценарий закрытия не-терминальной загрузки из веб-UI. Добавляются четыре: веб-UI не-терминальная (пустой код), терминальная (маркер + отказ Cancel), один и тот же stuck с двух поверхностей (маркер зависит от поверхности), замещение прежней диагностики стоп-краном. Плюс переписан сценарий повторного закрытия cancelled (no-op без записи и отказ Cancel конфликтом).

Выброшены два кандидата первой редакции. Сценарий «Закрытие зависшей загрузки» с GIVEN stuck (или failed/deferred) обещал пользовательский путь «Закрыть» для deferred, которого нет ни в одной поверхности, — ровно та ложная гарантия, ради снятия которой задача и заведена. Сценарий «Отклонение на ревью из Telegram» привязывал норму к кнопке карточки ревью, то есть заводил второй дом факту, живущему в review (D5), и дублировал сценарий веб-UI.

D7. Собственный код у Cancel — открытый вопрос, а не отвергнутый вариант

Первая редакция обосновывала потерю наблюдаемости так: «единый маркер потребовал бы звать Dismiss из не-терминальных состояний веб-UI, то есть менять рабочее поведение». Архитектурный проход показал, что это ложное основание: рассматривались вариант A (звать Dismiss из веб-UI — да, меняет поведение) и вариант C (ничего не делать), а третья форма не рассматривалась — дать Cancel собственный непустой код (user_cancel). Она меняет одну строку worker.go:985, не трогает ни состояний, ни файлов, ни интерфейса, и восстанавливает различение полностью.

Эта форма выходит за объявленную границу задачи: критерий приёмки A3 требует пустого диффа под internal/ и web/. Решать её не пайплайну — вопрос записан наружу (см. «Open Questions»), а изменение урезано до остатка: спека перестаёт лгать и перестаёт цементировать пустоту. Отсюда описательная форма в D3 — будущая одностроковая починка не станет нарушением спеки и не потребует нового change.

Заодно назван настоящий масштаб потери, которого постановка не видела: маркер сегодня кодирует поверхность, а не намерение. Один и тот же stuck, закрытый из Telegram, получает user_dismiss, а закрытый из веб-UI — пустой код. Это зафиксировано сценарием, чтобы вопрос не пришлось открывать заново.

D9. Исключение про уборку торрента висит на состоянии, а не на команде

Правка чекпоинта 2. Редакция D8 повесила carve-out на Cancel — и промахнулась осью. Уборка в worker.go:534 срабатывает по условию after.State != StateCatched, то есть безразлична к тому, какая команда увела задачу из catched; Dismiss из catched даёт тот же torrents/delete с deleteFiles=true. Проход adversary воспроизвёл это тестом (TestDismissInAddWindowCallsQbitDelete). Гейт Dismiss при этом шире гейта Cancel — значит формулировка «Dismiss не зовёт qBittorrent никогда» была ложной ровно там, где ошибиться дороже всего.

Исключение переформулировано по условию («закрытие любым путём, уведшее задачу из catched в окне после add») — как оно и записано в download-tracking, командо-нейтрально.

Заодно убрано утверждение «и данных пользователя не касается». Оно сильнее того, что гарантирует дом исключения: гард подтверждает отсутствие записи торрента в qBittorrent, но не отсутствие данных на диске, и adversary построил путь, на котором сносятся пред-существующие файлы пользователя (TestCancelInAddWindowDeletesPreExistingData). Сам этот дефект — в коде и пред-существующий; здесь снимается только ложная гарантия в тексте, а дефект уходит урожаем.

D10. Перепривязка названа не-лекарством

Правка чекпоинта 2. Первая редакция писала, что закрытие оставляет ссылки «без штатной команды снятия до повторной привязки» — то есть подавала relink лекарством. adversary показал тестами (TestDismissRelink, TestStrandedLink), что это не так: Apply заводит новый батч, а Undo и Delete работают только с последним, поэтому ссылка прежнего батча брошена навсегда, и последующее «полное удаление» перестаёт освобождать место. Текст приведён к факту; расширение Undo/Delete на все батчи — урожай.

D11. Подтверждение и лог перехода описаны как есть, а не как хотелось

Правка чекпоинта 2. Два новых обязательства первой редакции въезжали уже нарушенными:

• «SHALL требовать отдельного подтверждающего шага» — без JS диалога в веб-UI нет (гейт там только раскрытие <details> и явный submit), а в Telegram нет danger-зоны. Норма сужена до фактического гейта: обособление плюс дополнительный шаг там, где транспорт его поддерживает.
• «прежний код остаётся в логе перехода» — лог-строки Cancel и Dismiss прежнюю диагностику не пишут вовсе (worker.go:985-989, :1016-1020). Формулировка исправлена: причина восстановима только по более раннему переходу в failed/stuck и только пока её держит ретенция логов.

Оба раза выбран вариант «привести текст к факту», а не «оставить SHALL целью»: нормативный дом с заведомо невыполненным SHALL — это ровно тот дефект, ради снятия которого заведена задача.

D8. Отрицание побочных эффектов сужено до Dismiss с явным исключением

Первая редакция обобщила «команда SHALL только менять статус, qBittorrent не звать» с Dismiss на оба пути — и тем самым нормативно запретила уборку воркером собственного, только что добавленного торрента при отмене в окне после add. Эта уборка предписана download-tracking («Добавление пойманной загрузки в qBittorrent»), закреплена тестом TestProcessCatchedCancelledAfterAddRemovesTorrent и стоит вторым исключением инварианта «источник неприкосновенен» в CLAUDE.md. Изменение, чья цель — снять ложную гарантию, чуть не завело новую, да ещё и противоречащую соседней capability.

Отрицание возвращено к Dismiss, а для Cancel дано с явной ссылкой на дом исключения. Общее правило, которое отсюда следует: универсальное «SHALL NOT трогать X» обязано перечислять известные carve-out'ы или ссылаться на требование, где они живут.

Risks / Trade-offs

• [Асимметрия поверхностей описана и тем самым узаконена, а завтра её захотят выровнять] → Описательная форма (D2) выравнивание не блокирует: спека не станет ложной от того, что веб-UI добавит «Закрыть» на stuck. Нормативны только гарантия закрытия и гейты доменных путей.
• [Прецедент «спека следует за кодом» применяется буквально] → Риск унаследован от ADR-2026-08-06 и там же оговорён. Условие приёма проверено поимённо и выполнено не целиком: для обещания доступности — да, для обещания различимости — нет, поэтому второе спекой не закрепляется (D1, D7). Это и есть защита от буквального применения.
• [Новые сценарии не имеют теста-оракула] → Изменение чисто текстовое, гейт его регрессию не покрасит. Оракулом остаётся openspec validate --strict (форма) и чтение кода (содержание). Это идёт в границы покрытия ревью, а не замалчивается. Отдельно: клавиатуры Telegram не покрыты тестами вовсе, поэтому описанная в требовании раскладка по этой поверхности держится только на чтении render.go.
• [Требование выросло в объёме] → Выросло сознательно: раньше оно было короче своей же предметной области. Раскладка клавиатур в него не заехала (D2), поэтому косметическая правка UI его не тронет.
• [Часть найденного ревью не закрыта этим изменением] → Отдано урожаем, а не замолчано (полный список с оракулами — в review/triage.md): гард окна после add подтверждает отсутствие торрента, но не данных, и сносит пред-существующие файлы пользователя (кандидат critical, воспроизведён тестом); Undo/Delete работают только с последним батчем; прежняя диагностика не дублируется в лог перехода; «per-download блокировка» — на деле глобальный мьютекс, файловый ввод-вывод идёт под ним; дефолтный список даёт SCAN download, а cancelled копятся без ретеншена; та же no-JS-дыра в пред-существующем требовании «Полное удаление»; гонка «кнопка отрисована — состояние ушло» не описана ни одним требованием проекта; литералы error_code рассыпаны по трём спекам без сводной таблицы.
• [Кросс-ссылки в openspec/specs/ никем не проверяются] → Шаг canon гейта обходит только docs/ и CLAUDE.md. Первая редакция принесла в спеку markdown-ссылку, не резолвившуюся ни из change, ни после архивации; она заменена бэктик-путём — это и есть сложившаяся в openspec/specs/ конвенция (markdown-ссылок там нет ни одной). Promote-кандидат отдан урожаем.

Open Questions

• Дать ли Cancel собственный непустой error_code (напр. user_cancel). Цена — одна строка worker.go:985 плюс строка в docs/database.md; выигрыш — различение «пользователь отменил активную» / «стоп-кран» / «сверка» в диагностике восстанавливается полностью, и «известное ограничение» из требования исчезает. Не делается здесь: выходит за границу задачи (критерий приёмки A3 — пустой дифф под internal/). Пока решения нет, стоит то, что описано: маркер кодирует поверхность, а не намерение. Рекомендация — завести: цена несоразмерно мала.
• Стоит ли давать dismiss в REST ради равенства транспортов. Сегодня REST помечен опциональным и отдаёт только cancel; вопрос не блокирует изменение.