houseplan-card/docs/reviews/SPEC-REVIEW-406-r3.md

SPEC-REVIEW-406-r3

• Issue: #406
• ТЗ: docs/specs/406-beta2-polish.md, ветка issue/406-beta2-polish, ревизия 3, SHA c43051ac (тот же коммит, что назвал владелец в передаче на ревью: «Head: c43051ac»)
• Этап: spec (PROCESS.md §2.4)
• Заход: r3 · блокирующих циклов израсходовано 2 из 4
• Вердикт: жёлтый

Почему разбор по дельте, а не заново

Предыдущий вердикт (SPEC-REVIEW-406-r2) получен на SHA 0d5b52d1. Этот SHA существует на текущем дереве (git cat-file -t 0d5b52d1 → commit), и git merge-base 0d5b52d1 origin/dev равен b04387ce — тому же коммиту, что и сам origin/dev сейчас: ветка dev не продвинулась с момента ребейза перед r2, повторного ребейза между r2 и r3 не было. Это не случай §2.10 «ребейз на ушедший вперёд dev».

Дельта объявлена как git diff 0d5b52d1..c43051ac (плюс два новых файла docs/reviews/SPEC-REVIEW-406-r{1,2}.md, не относящихся к ТЗ). Диапазон origin/dev...HEAD по-прежнему состоит только из документов — продуктового кода нет, гейты tsc/test/build неприменимы, тот же факт, что в r1/r2.

Дельта в самом ТЗ ограничена: убран раздел (д) целиком, переписаны контракты (б) и (в) (они образуют одну технически связанную развилку — HA-ветка против нативной), скорректированы AC6–AC8, план автотестов, риски, откат, release-артефакты и скоуп/не-скоуп в частях, которые ссылались на (д). Разделы (а) и (г) в дифф не попали ни строкой. Контракт поведения меняется — именно для (б)/(в), и именно поэтому ниже они разобраны заново по существу, а не по формуле «раз тема та же — переносим вывод r2». (а) и (г) наследуются.

Скоуп

Без изменений по существу, но пересчитан: было пять пунктов на трёх поверхностях, стало четыре пункта на трёх поверхностях (словари i18n, hp-dialog, снапшоты переезда area) — пункт (д) выведен из скоупа, так как дефект уже устранён в #409 коммитом 8119c523 до того, как эта ревизия дошла до ревью. Обоснование трека small/полный трек не изменилось.

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

Прочитаны PROCESS.md §2.4, §2.9, §2.10, §4, §7.1, §7.2; тело issue #406 и все комментарии, включая передачу на повторное ревью revision 3 (описывает оба исправления и три проверки: check-docs.mjs, process-gate.mjs --issues, git diff --check — все green); docs/reviews/SPEC-REVIEW-406-r1.md и -r2.md целиком.

Само ТЗ вычитано целиком построчно на SHA c43051ac, не только дельта — чтобы поймать противоречия между новым текстом (б) и разделами, которые дифф не тронул (UX, Release-артефакты), что и дало находку №1 ниже.

Специально для закрытия находки r2 №2 (механизм HA-ветки не назван) — внешняя проверка, не чтение только этого репозитория: скачан реальный исходник home-assistant-frontend==20260729.7 (версия подтверждена tests_backend/requirements.txt:34, комментарий там же объясняет, что она берётся из констрейнтов закреплённого HA 2026.8.3, а не назначена вручную) — https://raw.githubusercontent.com/home-assistant/frontend/20260729.7/src/components/ha-dialog.ts, 560 строк, прочитан целиком. Проверено построчно:

• @property({ attribute: 'aria-describedby' }) public ariaDescribedBy?: string (строка 92-93) действительно передаётся во внутренний <wa-dialog aria-describedby=${ifDefined(this.ariaDescribedBy)}> (строка 168, внутри render(), строки 158-224);
• @property({ reflect: true }) public type: 'alert' | 'standard' = 'standard' (строка 98-99) отражается только на хосте (grep -n "this\.type" по всему файлу — пусто вне JSDoc/деклараций свойства) и используется только в CSS через :host([type="standard"]) (строки 448, 454) — в render() тег <wa-dialog> не получает от this.type ни атрибута, ни свойства, роль нигде явно не устанавливается.

Это ровно то, что ТЗ теперь утверждает буквально — не пересказ, а подтверждённый цитированием факт.

Дополнительно перечитаны src/hp-dialog.ts (весь файл, включая шапочный doc-comment строки 24-31, стили строки 41-216, render() строки 437-482, connectedCallback строки 231-242), src/hp-confirm.ts (весь файл, 72 строки) и src/houseplan-card.ts вокруг kind: 'warning' — не для подтверждения того, что уже подтвердили r1/r2 (это унаследовано), а чтобы установить, действительно ли сегодня hp-confirm рендерится через HA-ветку в реальном HA, — это стало основанием находки №1 ниже.

Закрытие раунда r2

Находка r2	Чем закрыта	Где видно
№1 (д) контракт описывает уже исправленный дефект, расходится с реально смёрженным поведением	Раздел (д) удалён из ТЗ целиком: заголовок, контракт, AC12/AC13 (были — теперь бюджет initial стал AC12), пункт плана автотестов «7. Приёмка с replace: []», мутант не заводился и не упоминается. «Не в скоупе» получил явную строку с точной причиной: «история screenshot-acceptance — дефект уже исправлен в #409 коммитом 8119c523… #406 не меняет и не дублирует этот контракт»	docs/specs/406-beta2-polish.md:176-190 (скоуп/не-скоуп), diff 0d5b52d1..c43051ac показывает раздел (д) только в --строках. Перепроверено: grep -n "AC13|AC14" по текущему файлу — пусто; «Откат» пересчитан с пяти правок на четыре (:321-326); Release-артефакты — с «остальные четыре пункта» на «остальные три» (:328-333)
№2 (б) контракт не называет механизм, которым HA-ветка получает alertdialog/aria-describedby	Раздел (б) получил новый абзац с цитатой закреплённой версии home-assistant-frontend (строки 110-118) и переписанный практический абзац (строки 120-129): решение явное — .ariaDescribedBy есть и реально долетает до внутреннего диалога, но type="alert" роль не передаёт, поэтому alert-подтверждения всегда используют нативный <dialog role="alertdialog">, даже когда ha-dialog зарегистрирован; обычные диалоги вне hp-confirm — по-прежнему HA-ветка с .ariaLabelledBy/.ariaDescribedBy. AC6/AC7/AC8 (:232-249) и план автотестов (:266-273) переписаны под эту развилку	Независимо перепроверено чтением реального ha-dialog.ts тега 20260729.7 (раздел «Как проверялось» выше) — утверждение ТЗ о поведении стороннего компонента подтверждено, а не принято на слово

Обе находки r2 закрыты по существу. Разбор (б)/(в) по факту закрытия вскрыл новую находку — она не переоткрывает находки r1/r2, это независимый дефект, ставший видимым только после того, как r3 назвал конкретный механизм (до этого, в r1/r2, контракт был расплывчат, и вопрос «что увидит пользователь» было не к чему привязать).

Унаследовано из r2

Разделы (а) «Мёртвые строки в словарях» и (г) «Снапшот копит записи исчезнувших устройств» дельтой не задеты (не встречаются ни в одной -/+ строке git diff 0d5b52d1..c43051ac, кроме одного упоминания (а) в перечислении «Приоритет»/«Сценарий», которое не меняет контракт). Их фактическая проверка (числа по словарю, 13 мёртвых ключей, 19 живых *.help.aria, коллизия с test/unified-wall-tool-source.test.mjs, механика resolveDeviceAreaRelocations/markerAreaSnapshotOf, номера строк) принята без повторной перепроверки из docs/reviews/SPEC-REVIEW-406-r2.md, разделы «Что проверено и корректно», на SHA 0d5b52d1.

Также унаследована структурная оценка §7.1 (все обязательные разделы присутствуют, продуктовых технических вопросов владельцу не вынесено, легитимность полного трека по docs/SCOPE.md) — она подтверждена в r2 и не пересчитывалась заново построчно для разделов, которых дельта не касается; для (б)/(в)/скоупа/UX/release-артефактов она перепроверена заново (см. ниже).

Находки

[Medium, в скоупе] №1 — UX и Release-артефакты утверждают «оформление не меняется», хотя раздел (б) в этой же ревизии вводит видимый пользователю переход confirm-диалогов с HA-оформления на нативное

Файл: docs/specs/406-beta2-polish.md, раздел (б) «Практически» (строки 120-129) против раздела «UX» (строки 192-197) и «Release-артефакты» (строки 328-333).

Что не так: раздел (б) в этой ревизии впервые называет конкретный механизм (закрытие находки r2 №2) — и этот механизм состоит в том, что hp-confirm (все виды: и destructive, и warning) больше не следует общему правилу hp-dialog._useHaDialog = !!customElements.get('ha-dialog') (hp-dialog.ts:240), а принудительно рендерит нативный <dialog> даже когда ha-dialog зарегистрирован (строки 124-127: «hp-dialog намеренно выбирает нативный <dialog role="alertdialog"> даже при наличии ha-dialog»).

Сегодня, до этой задачи, hp-confirm.ts не делает никакого выбора — он безусловно передаёт <hp-dialog> (hp-confirm.ts:36-61), и собственный doc-comment hp-dialog.ts:24-31 прямым текстом говорит: «Home Assistant provides the visual surface and focus trap through ha-dialog. The native dialog branch keeps the standalone demo usable without mocking HA frontend internals» — то есть в реальном Home Assistant (где ha-dialog всегда зарегистрирован) все семь destructive-подтверждений и один warning сегодня рендерятся через ha-dialog: собственный заголовок HA (ha-dialog-header), анимации, wa-dialog-обвязку. Нативная ветка сегодня — исключительно путь standalone-демо без HA. Проверено также, что в коде нет ни одного прецедента принудительного игнорирования _useHaDialog (grep -rn "_useHaDialog" src/*.ts — пять использований, ни одно не форсирует ветку для конкретного компонента) — то есть это решение (б) вводит новый класс поведения, а не продолжает существующий.

После задачи это же множество диалогов — каждое подтверждение удаления и единственное подтверждение разблокировки замка — у каждого реального пользователя Home Assistant сменит визуальную оболочку с HA-хрома на собственную вёрстку hp-dialog (.header/.close/.surface, строки 127-216 того же файла): другой DOM/CSS-путь заголовка, другая анимация появления, другой фокус-трап (нативный <dialog> вместо wa-dialog). Цвета границы/фона/скругления действительно частично совпадают (--hp-accent, --card-background-color, --rad-l заданы для обеих веток), но это не то же самое, что «оформление не меняется» — структура заголовка, анимация и поведение фокуса всё равно другие.

При этом раздел «UX» (не менявшийся ни в одной из трёх ревизий, git diff подтверждает отсутствие правок этого раздела за весь трек) заявляет: «Оформление не меняется. Меняется то, что слышит пользователь скринридера…» — и раздел «Release-артефакты» относит к User-Visible только факт объявления скринридером, помечая остальные три пункта внутренними, а строку «Скриншоты не меняются: диалог в статике не открыт» приводит как единственное следствие для документации.

Сценарий отказа: реализация по тексту ТЗ корректно уходит с HA-хрома на нативный <dialog> для всех alert-подтверждений (AC6/AC8 зелёные), но CHANGELOG не получает пункта об этом (Release-артефакты явно требуют только одну строку — про скринридер), а автор код-ревью следующего раунда, доверяя разделу UX буквально, не станет искать визуальный регресс на реальном HA — хотя пользователь при первом же «Удалить комнату?» увидит непривычно выглядящий диалог вместо знакомого HA-стиля. Отдельный риск: если несоответствие всплывёт в проде, это будет воспринято как баг (незапланированный визуальный дрейф), хотя по факту это — осознанное, но нигде не заявленное инженерное решение.

Ожидаемо: раздел «UX» и «Release-артефакты» приведены в соответствие с разделом (б) — либо явно признаётся и документируется видимая смена оформления confirm-диалогов (HA-хром → нативный hp-dialog) как User-Visible-пункт в обоих CHANGELOG, либо владелец фиксирует иной баланс (например, принять расхождение только для warning, а не для всех destructive, если визуальная консистентность важнее для частых операций) — но текущее молчаливое «не меняется» рядом с разделом, который явно описывает смену ветки рендера, оставлять нельзя.

Что проверено и корректно

• Обе находки r2 закрыты по существу, не косметически — подробности в разделе «Закрытие раунда r2» выше; находка №2 закрыта с независимой внешней проверкой (реальный исходник закреплённой версии home-assistant-frontend, а не доверие цитате в ТЗ).
• §7.1, обязательные разделы — все присутствуют и после сокращения документа: сценарий, что человек увидит до/после, проблема+контракт по каждому из четырёх пунктов, скоуп/не-скоуп, UX, модель данных и миграция, i18n, AC1-AC12 с доказательством, план автотестов, риски, откат, release-артефакты.
• Внутренняя согласованность после удаления (д): нет висячих ссылок на AC13/AC14, счётчики «пять правок» → «четыре», «остальные четыре пункта» → «остальные три» пересчитаны верно, мутант и юнит-пункт плана, относившиеся к (д), убраны вместе с разделом, а не оставлены сиротами.
• AC6-AC8 и обновлённый план автотестов внутренне непротиворечивы: они корректно описывают именно ту развилку, которую называет обновлённый (б) — alert всегда нативный, обычные диалоги вне hp-confirm — всегда HA-ветка при её наличии.
• Продуктовых технических вопросов владельцу не вынесено — как и в r1/r2.
• Три проверки автора (check-docs.mjs, process-gate.mjs --issues, git diff --check), названные в передаче на ревью, — дешёвые, применимые к doc-only дереву; не перепроверял отдельно, так как они не относятся к предмету находок этого раунда (документная гигиена, не контракт).

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

• Гейты tsc/test/build — не гонял: диапазон origin/dev...HEAD по-прежнему состоит только из doc-файлов (три .md), продуктового кода нет. То же основание, что в r1/r2.
• Не пересчитывал заново инвентарь мёртвых ключей (а) и механику снапшотов (г) — унаследовано из r2 (SHA 0d5b52d1), дельта их не касается (см. раздел «Унаследовано»).
• Не проверял поведение реального wa-dialog (@home-assistant/webawesome) на предмет того, передаёт ли он сам role от type, помимо того, что ha-dialog.ts этого не делает явно, — для контракта (б) достаточно доказать, что ha-dialog.ts не передаёт type/role внутрь, а глубже в сторонний пакет ТЗ и не заходит (сознательно, см. риск «#406 не патчит shadow DOM»).
• Не проверял субъективную величину визуального расхождения между HA-хромом и нативной веткой на глаз (скриншот/рендер) — вывод находки №1 основан на структурном сравнении кода (разные DOM-пути, разный фокус-трап, разный элемент заголовка), не на визуальном сравнении пикселей; для целей этого ревью (обнаружить неучтённое расхождение с разделом UX) этого достаточно, количественная оценка — дело код-ревью или ручного смотра при реализации.
• Не проверял scripts/mutation-gate.mjs на техническую реализуемость трёх заявленных мутантов — на этапе ТЗ это описание намерения, не код; та же позиция, что в r1/r2.

Вердикт

Вердикт: жёлтый · заход r3 · блокирующих циклов 2/4 · High: 0 · Medium: 1 → в задаче