houseplan-card/docs/reviews/SPEC-REVIEW-402-r1.md

SPEC-REVIEW-402-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/402
• Артефакт ТЗ: docs/specs/402-confirm-outside-main-branch.md (полный трек, класс A)
• Заход: r1 · лимит циклов ревью ТЗ для полного трека — 4 (§4), израсходовано 0
• Ревьюер: Claude (роль «ревьюер ТЗ»), независимая сессия, без устных пояснений автора
• База сравнения: HEAD d94db87e (коммит, добавивший спецификацию)

Скоуп ревью

Первый раунд ревью ТЗ для #402: регресс подтверждения опасного действия (hp-confirm), которое рендерится только в финальной ветке render() (src/houseplan-card.ts) и поэтому недоступно/теряется в остальных ветках (онбординг «нет пространств», fixed_floor pending/invalid, !space). Задача полного трека (P1, bug, класс A) — файл ТЗ обязателен, что и сделано.

Как проверялось

1. Прочитаны docs/SCOPE.md, AGENTS.md, PROCESS.md целиком (разделы §2.4, §2.5, §5, §7.1, §7.2), тело issue #402 и единственный комментарий (аналитика S2).
2. Прочитан весь текст ТЗ docs/specs/402-confirm-outside-main-branch.md.
3. Каждое фактическое утверждение ТЗ о коде сверено с текущим деревом на SHA d94db87e:
   • структура render() (src/houseplan-card.ts:11165-11884) — все семь ранних веток и их точки возврата;
   • HpConfirmController (src/danger-confirm.ts) — поведение confirm / resolve / cancel;
   • вызов _confirmDanger из _deleteServerPlan (src/houseplan-onboarding-runtime.ts:218-224, клик на :273);
   • все восемь call site'ов _confirmDanger (houseplan-card.ts, houseplan-editor-runtime.ts ×5, houseplan-onboarding-runtime.ts ×2);
   • расположение _tapConfirm (:11852-11868) и _vacCalConfirm (:11802-11812) относительно _dangerConfirm (:11872-11878);
   • импорт hp-confirm — проверено, что он не ленивый (houseplan-card.ts:14, верхнеуровневый import), что подтверждает заявление ТЗ об отсутствии влияния на бюджет (AC7);
   • использование noChange во всём src/** — подтверждено, что сентинел нигде не оборачивается в шаблон (grep noChange), это делает техническое утверждение границы ТЗ («noChange нельзя обернуть») фактом, а не догадкой.
4. Проверено соответствие терминологии docs/USER-GUIDE.ru.md (раздел про общий диалог подтверждения) — видимых текстов ТЗ не меняет, конфликта нет.
5. Проверено docs/TOUCH-SUPPORT.md и DoR-чек-лист §2.5 на предмет обязательного пункта про touch/kiosk — см. находку H1.
6. Проверены обязательные разделы §7.1 — присутствуют все (сценарий · что человек увидит · проблема/контракт · скоуп/не-скоуп · UX · модель данных · i18n · AC1-7 с доказательством · план автотестов · риски · откат · release-артефакты).
7. Гейты кода (tsc, test, build) не гонялись: на этапе ТЗ продуктового диффа ещё нет, гонять их не над чем (см. «Чего не проверял»).

Находки

H1 (High, блокирует). ТЗ не называет влияние на touch/kiosk — обязательный, объявленный блокирующим пункт DoR

Где: весь файл docs/specs/402-confirm-outside-main-branch.md — ни разу не упоминает touch, kiosk или TOUCH-SUPPORT.md (grep -i touch|kiosk по файлу — ноль совпадений).

Почему это находка, а не формальность. PROCESS.md §2.5 перечисляет пункты «Готово к разработке» и явно помечает один из них как блокирующий отдельно от остальных: «влияние на touch по docs/TOUCH-SUPPORT.md (View и киоск — блокирующие)», и там же: «Если хоть один пункт не выполнен — статус не «Готово к разработке»». TOUCH-SUPPORT.md со своей стороны требует того же прямым текстом: «New editor feature specifications … must state one of: Touch editor: supported / best effort / intentionally degraded / not exposed».

Затронутая этим ТЗ поверхность — не абстрактный служебный код: это ровно диалог <hp-confirm> в состоянии «нет пространств» (онбординг) и в fixed_floor pending/invalid, то есть экран, который согласно TOUCH-SUPPORT.md относится к категории «View dialogs and safe device actions» — «Fully supported» на touch, без исключений best-effort. Часть затронутых call site'ов (houseplan-editor-runtime.ts, 5 мест) при этом принадлежит редакторам, для которых допустима best-effort деградация — но только если она явно объявлена, а не подразумевается молчанием.

Симптом отсутствия анализа: без явного утверждения нельзя отличить «автор проверил — влияния нет» от «автор не думал про touch вовсе». Это особенно значимо здесь, потому что рефакторинг двигает hp-confirm из внутреннего дочернего узла одной <ha-card> в узел, рендерящийся отдельно от конкретной ветки разметки (см. Риск «двойной рендер диалога» в самом ТЗ) — у смены места крепления DOM-узла есть техническая возможность задеть touch-специфичные вещи (portal/DOM-scope для dialog.showModal(), pointer-events, :focus-trap), даже если по факту не заденет.

Фактическая оценка (для экономии цикла): содержательно последствий, скорее всего, нет — <hp-confirm> остаётся тем же кастомным элементом с тем же shadow DOM и той же логикой модального диалога независимо от того, чьим прямым потомком в основном дереве он является; ни один AC1-7 не описывает изменение верстки, жестов или поведения hp-confirm самого по себе. Но это вывод ревьюера, а не факт, зафиксированный автором в ТЗ — а фиксировать его обязан автор (правило #163 «New editor feature specifications … must state one of»).

Требуемая правка: добавить в ТЗ явную строку по образцу Touch: View/kiosk — fully supported, без изменений (тот же <hp-confirm>, маршрут рендера не меняет разметку/жесты диалога), и отдельно — Touch editor: supported для пяти call site'ов из houseplan-editor-runtime.ts, если они действительно не деградируют. Это правка одной-двух строк текста, не кода.

M1 (Medium, в скоупе задачи). «Не-скоуп»-обоснование для _tapConfirm/_vacCalConfirm содержит фактическую неточность

Где: docs/specs/402-confirm-outside-main-branch.md, раздел «Скоуп / не-скоуп»: «Не в скоупе: … _tapConfirm и _vacCalConfirm — у них своя механика и свои ветки.»

Проверено чтением кода: _tapConfirm рендерится в src/houseplan-card.ts:11852-11868, _vacCalConfirm — в :11802-11812, _dangerConfirm — в :11872-11878. Все три блока лежат в одной и той же финальной ветке render() (последний <ha-card>, тот же самый шаблон, между ними нет ни одного return). Утверждение «свои ветки» в буквальном прочтении неверно: у них нет собственных веток render() — они делят ровно ту же ветку, что и _dangerConfirm до этого фикса, и подвержены тому же классу дефекта («открытое подтверждение исчезает при смене ветки», вторая половина дефекта из аналитики S2), например если многоклиентская синхронизация (J6, docs/SCOPE.md) уводит карточку в fixed_floor pending или обнуляет model.length пока открыт _tapConfirm/_vacCalConfirm.

Отличие от _dangerConfirm, которое у ревьюера НЕ вызывает вопросов и, похоже, и есть настоящая причина исключения: _tapConfirm/_vacCalConfirm не используют HpConfirmController и не отдают вызывающему Promise — exec() вызывается синхронно по клику, поэтому «вечно висящего промиса» у них в принципе не бывает (при потере диалога они не блокируют await вызывающего, а просто становятся недоступны до следующего рендера основной ветки). А сами точки входа (marker.tap_confirm, календарь пылесоса) физически недостижимы из веток онбординга/fixed_floor/!space — там нет устройств на плане, значит буквальный сценарий issue их не касается.

Это делает исключение из скоупа разумным по существу, но обоснование в тексте — неверным: «свои ветки» вместо настоящей причины («синхронный exec без промиса» + «недостижимость точки входа из веток вне основной»). Ложное обоснование опасно не абстрактно: тот, кто будет реализовывать вынос hp-confirm из финальной ветки, должен точно знать, что _tapConfirm/_vacCalConfirm физически стоят в той же ветке и их нельзя случайно утащить вместе с _dangerConfirm при выносе блока — а формулировка «у них свои ветки» наводит на обратное представление.

Требуемая правка: заменить формулировку на техническую причину исключения (синхронный exec, недостижимость входа) и явно предупредить реализацию не трогать расположение этих двух блоков при выносе _dangerConfirm. Опционально (не обязательно для этого issue) — упомянуть остаточный риск «уже открытый _tapConfirm/_vacCalConfirm теряется при смене ветки во время многоклиентской синхронизации» как кандидата в отдельный issue, если владелец сочтёт его достаточно вероятным; в скоупе #402 фиксировать не обязательно — issue именно про мёртвую кнопку и висящий промис, которых у этих двух объектов нет.

Что проверено и признано корректным

• Диагноз дефекта — точен и воспроизводим по строкам: render() действительно возвращает hp-confirm только в финальной ветке (:11872), все более ранние return (:11166, :11170, :11171, fixed_floor pending/invalid, !model.length, !space) реально существуют и реально не содержат hp-confirm.
• HpConfirmController описан верно: cancel() действительно резолвит false через resolve(), resolve() сверяет токен, новый confirm() отменяет предыдущий запрос (src/danger-confirm.ts:47-72) — контроллер не участвует в дефекте, претензия ТЗ обоснована.
• Буквальный сценарий issue (_deleteServerPlan из онбординга) сверен построчно: src/houseplan-onboarding-runtime.ts:218-224 вызывает this.host._confirmDanger, кнопка в :273 — реальная причина «мёртвой корзины» из issue.
• Техническое утверждение о noChange («нельзя обернуть в шаблон») — подтверждено: во всём src/** noChange возвращается только как значение render() целиком (houseplan-card.ts, editor.ts, space-card.ts, space-editor.ts), ни разу не встречается внутри ${…} — граница ТЗ не придумана, а списана с уже действующего паттерна кодовой базы.
• AC1-AC4, AC6 — проверяемы, у каждого назван способ доказательства (смок), и способ реалистичен: demo/smoke_danger_confirmation.mjs уже существует и уже покрывает контракт диалога, дополнение под новые ветки — органичное расширение того же файла.
• AC5 (иммедиат-отказ в !_config||!hass и warm) — продуман корректно: !hass/!_config не могут стать false→true→false в течение жизни примонтированной карточки (Lovelace не сбрасывает hass/config в falsy после первичной установки), то есть эта ветка достижима только до первого рендера — отказывать там немедленно безопасно и не теряет открытый диалог (терять нечего). Ветка warm реально достижима в течение сессии (смена языка), и там noChange сохраняет уже показанный диалог нетронутым (Lit не трогает DOM) — то есть AC5 верно ограничивает немедленный отказ только НОВЫМИ запросами, не описывая (и не должен описывать) отмену уже открытых.
• AC7 (бюджет) — hp-confirm импортируется в шапке файла обычным (не ленивым) import (houseplan-card.ts:14), поэтому перемещение точки рендера не добавляет новый чанк/зависимость — заявление «правка структурная, бюджет не растёт» подтверждается фактическим импортом.
• Скоуп/не-скоуп в остальном — граница с #32 (содержимое диалога, ревалидация после await) и с #406 (alertdialog/aria-describedby) названа явно и не пересекается с контрактом этого ТЗ.
• Обязательные разделы §7.1 — все присутствуют, включая «откат» и «release-артефакты» (changelog RU+EN).
• Соответствие docs/SCOPE.md: чинит J4 (онбординг, «zero to a working plan») и снимает риск для J6 (multi-client sync может вызвать смену ветки под открытым диалогом) — задача не расширяет продукт, а восстанавливает ранее рабочее поведение (регресс против до-#32).
• Метки issue (bug, P1, S4-spec-review, без small/trivial) согласуются с заявленным в ТЗ полным треком.

Чего не проверял

• Гейты кода (npx tsc --noEmit, npm test, npm run build, check-docs, смоки, bundle:budget) — не гонялись: на этапе ТЗ продуктового кода ещё нет, диффа для гейтов не существует. Это будет предметом код-ревью после реализации.
• scripts/mutation-gate.mjs / demo/smoke_danger_confirmation.mjs — не запускал, только убедился, что оба файла существуют и их формат (реестр мутантов, browser-smoke на реальной карточке) совместим с планом автотестов ТЗ.
• Таблицу docs/specs/README.md — строка для #402 в неё не добавлена, но это не регрессия этого ТЗ: специфика #395-#401 туда тоже не занесена (таблица не поддерживается систематически, известный долг §7.3 п.1 документа процесса), поэтому не поднимаю отдельной находкой.
• Реальный рендер в браузере — на этапе ТЗ кода нет, воспроизведение дефекта в описании ТЗ и issue взято на веру как «воспроизведено исполнением» автором аналитики; независимо не перепроверял (это будет предметом смок-доказательства в код-ревью).
• _tapConfirm/_vacCalConfirm как отдельный дефект — не завожу отдельный issue: по результату разбора (см. M1) это не тот же класс дефекта (нет висящего промиса, нет недостижимости из веток issue), поэтому это не «Medium вне скоупа» по #202, а неточность формулировки внутри текущего ТЗ — чинится правкой текста в этом же документе.