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

SPEC-REVIEW #440 — r1

• Issue: https://github.com/Matysh/houseplan-card/issues/440
• Этап: spec (PROCESS.md §2.4)
• ТЗ: docs/specs/440-v171-beta2-polish.md, коммит 735710f1
• Заход r1 · блокирующих циклов израсходовано 0/4
• Вердикт: зелёный

Скоуп ревью

Полный разбор — заход первый, дельты нет. ТЗ покрывает семь пунктов аудита v1.71.0-beta.2 (§3.3): (а) зависание verifier на не-обычном файле, (б) потеря pointer-modality на room pointermove при выключенном tooltip, (в) getter с побочным эффектом _dangerConfirmLocaleGate, (г) TOCTOU в физической инвентаризации ассетов + неверный HTTP 507, (д) source-regex свидетель AC5 #434, (е) отсутствие ретроактивных review-документов для #429/#430, (ж) importorskip("homeassistant"), скрывающий чистые Python-тесты канонизации.

Читал в заданном порядке: docs/SCOPE.md, PROCESS.md §1–§8, тело issue #440 и оба комментария (аналитика + сдача ТЗ), само ТЗ целиком, docs/TOUCH-SUPPORT.md §«Pointer modality and hover ownership».

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

Ревью ТЗ — не код-ревью, но каждое фактическое утверждение ТЗ о текущем поведении кода я сверил с реальным деревом на origin/issue/440-audit-polish (= 735710f1), чтобы отличить обоснованный контракт от догадки, выданной за факт:

Пункт ТЗ	Файл:строка	Что проверено
(а) verifier/FIFO	custom_components/houseplan/asset_integrity.py:42-129	_signature() = голый path.stat() (проходит на FIFO/device), _stream_sha256() открывает open("rb") без таймаута, followers ждут event.wait() без границы. Совпадает с описанием ТЗ дословно
(б) pointer modality	src/houseplan-card.ts:11589-11675, :7186-7193, :7291-7304	tip(e) (bound на @pointermove) при !showRoomTooltipOf(...) возвращается на 11592-11593 до вызова _notePointer; enterRoom (bound на @pointerenter) вызывает _notePointer всегда. Подтверждает узкую щель: смена pointer type внутри уже наведённой комнаты не долетает до _notePointer, когда tooltip выключен
(в) locale getter	src/houseplan-card.ts:2160-2166,2188,4193, src/i18n/language-runtime.ts:105-131	Геттер _dangerConfirmLocaleGate вызывает languageRenderGate(), которая мутирует host.inert, aria-busy, lang, два WeakSet, планирует requestUpdate() — вызывается из _confirmDanger() и updated(), вне рендера. Подтверждено
(г) TOCTOU/507	custom_components/houseplan/decor_assets.py:376-394, http_api.py:262-347	physical_asset_blobs не оборачивает path.stat(follow_symlinks=False) внутри цикла iterdir() — исчезновение даёт необработанный OSError, который поднимается через physical_asset_usage → _store() → перехватывается только на except OSError (500). Отдельно except DecorAssetError: … status=507 на строке 344 ловит любой DecorAssetError из _store(), включая invalid_image (273, 289) — сейчас всегда 507. Оба факта подтверждены
(д) AC5 regex	test/space-card-audit-lows.test.mjs:28-39	Ровно пять assert.match по тексту src/space-card.ts/src/config-store.ts, как описано в ТЗ
(ж) importorskip	tests_backend/test_coordinate_canonicalization.py:1-40	Модульный pytest.importorskip("homeassistant") стоит выше импорта coordinate_canonicalization и DECOR_BOX_KINDS — чистые тесты (test_decor_box_catalog_matches_shared_contract, test_all_4801_lattice_nodes_and_nine_decimal_forms_share_exact_bits) реально скипаются без HA
AC6 инфраструктура	scripts/mutation-gate.mjs:2402-2450	Мутанты image-box-python-canonicalization-omitted и all_4801_lattice_nodes... уже указывают на tests_backend/test_coordinate_canonicalization.py через backend-test-guard.mjs — перенаправление на новый модуль механически осуществимо, путь не изобретён
TOUCH-SUPPORT.md	docs/TOUCH-SUPPORT.md:43-57	«Touch and pen input immediately clear transient room and device hover, including tooltips» — контракт п.2 ТЗ («независимо от настройки») не изобретён, а прямая цитата канона
i18n	src/i18n/{en,ru,de,fr}.json	Все четыре словаря существуют, ТЗ верно перечисляет «не меняются»
Смоки в «Затронутых модулях»	ls demo/smoke_danger_confirm_branches.mjs demo/smoke_room_tooltip_toggle.mjs demo/smoke_space_card_decor_capability.mjs	Все три файла существуют
docs/specs/README.md	git show HEAD -- docs/specs/README.md	Строка на #440 добавлена в том же коммите, ссылка на файл корректна

Проверка кодом не подтверждает и не опровергает пункт (е) — это решение процесса, а не факт кода; ТЗ фиксирует его как аналитический вывод без кодовых изменений, что соответствует PROCESS.md §1 (инфраструктурные задачи без файлов класса A идут без ТЗ/код-ревью).

§7.1 — обязательные разделы

Все присутствуют: Сценарий · Что человек увидит до и после · Проблема и подтверждённые причины · Скоуп/Не-скоуп · Контракт поведения (7 пунктов) · Touch и доступность (UX) · Модель данных, совместимость и i18n · Производительность и безопасность · Затронутые модули · Критерии приёмки AC1–AC8 с доказательством · таблица «чем краснеет» для AC1–AC6 · План автотестов · Риски · Откат · Release-артефакты · блок принятых технических предположений. Трек (full) обоснован явно названным нарушенным критерием лёгкого трека (несколько поверхностей, TS+Python, touch-контракт) — соответствует PROCESS.md §5.

Догадки, выданные за факт

Не найдены. Каждое утверждение о текущем поведении сверено с кодом (таблица выше) и совпадает буквально. Технические решения, не вытекающие однозначно из существующего контракта (точное значение follower-таймаута, точное имя command-метода locale-gate, единство/раздельность test harness), явно вынесены в раздел «Принятые технические предположения» с пометкой «может быть свободно скорректировано ревьюером» — я эту пометку принимаю без правок: ни одно из шести предположений не меняет продуктовый контракт и не требует продуктового решения владельца.

Продуктовые вопросы владельцу

Нет. Ни один AC не требует решения о том, что человек видит или делает — задача исключительно про hardening существующих контрактов (пункты 1–4, 6) и про качество тестового свидетеля (пункты 5, 7), без нового UX. Раздел «Аналитика» в issue уже верно это фиксирует.

Находки

Ни одной блокирующей (High) или требующей возврата (Medium) находки.

Low (снимается без правки, с записью). Формулировка контракта AC4/§4 «Если root либо отдельная entry исчезла… этот кандидат пропускается» лексически объединяет два разных случая: исчезновение одной записи между iterdir() и stat() (ровно то, что описывает аудит и что покрывает план автотестов п.4) и исчезновение самого каталога root целиком (у которого нет «кандидата» — пропадать нечему, весь скан просто должен дать count=0, bytes=0 без исключения). План автотестов раздела «План автотестов» п.4 явно строит только первый случай (подмена stat одного кандидата), про второй не говорит. Это не блокирует: реализация свободна закрыть оба случая одним try/except вокруг iterdir()-цикла, а второй случай на порядок более гипотетичен (нужно, чтобы директория ассетов исчезла во время активного апдейта HA) и не был частью исходной находки аудита (г), которая специально про TOCTOU на отдельной записи. Снимаю без возврата автору — реализация и ревьюер кода в состоянии решить механику по контексту; если разработчик по факту не покроет root-vanishing веткой теста, это не расхождение с ТЗ, а вопрос полноты теста для код-ревью.

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

• Все семь пунктов аудита в ТЗ имеют прямое соответствие в коде на текущем SHA — ни один не является пересказом чужих слов без проверки.
• AC1–AC8 однозначны, у каждого указан способ доказательства; AC1–AC6 дополнительно снабжены таблицей «чем краснеет» — это избыточно для этапа spec (обязательно только для код-ревью, §2.7), но облегчает будущий цикл.
• Скоуп/не-скоуп разделены чётко, включая явный отказ трогать API/схему/ golden/performance-baseline.
• Откат описан как atomic revert с оговоркой про частичный откат по компонентам — соответствует стилю других ТЗ пакетных полишей.
• Touch-контракт п.2 — прямая цитата docs/TOUCH-SUPPORT.md, не изобретение.
• i18n/release-артефакты корректны по факту дерева (все 4 локали существуют, правок нет; docs/specs/README.md обновлён в том же коммите).
• Названные для редактирования тестовые/смок-файлы существуют в дереве.

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

• Не запускал автотесты/гейты — ревью ТЗ не требует прогона (нет кода для тестирования, реализация ещё не начата).
• Не проверял custom_components/houseplan/http_api.py целиком построчно — только участки, относящиеся к пунктам (а) и (г).
• Не проверял docs/ARCHITECTURE.md/docs/TESTING.md на точное текущее содержание тех разделов, которые ТЗ предлагает обновить «если требуют» — условная формулировка допустима на этапе ТЗ (детали редактирования документации решает исполнитель).
• Не оценивал реализуемость точного числового значения follower-таймаута — ТЗ прямо помечает это как техническое предположение, свободное для корректировки, поэтому численное значение не является предметом ревью ТЗ.

Материал раунда

• SHA ТЗ: 735710f1 (ветка origin/issue/440-audit-polish, HEAD на момент ревью).
• Дерево материала: рабочая копия на 735710f1, git status чист.
• Файл ТЗ: docs/specs/440-v171-beta2-polish.md (422 строки, добавлен этим коммитом вместе с записью в docs/specs/README.md).

---

Материал раунда

• Ветка: issue/440-audit-polish, коммит 735710f16b8f — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
• Дерево материала: 927a83664db31061974ea9103581848a0cc8470e

  git log --all --format='%H %T' | grep 927a83664db3
  

• ТЗ docs/specs/440-v171-beta2-polish.md, блоб 0de292e2f2dc734f08a9f3eb4d37d2a6734da3e4

  git log --all --find-object=0de292e2f2dc734f08a9f3eb4d37d2a6734da3e4 -- docs/specs/440-v171-beta2-polish.md